dsh-permission-rules 0.3.0 → 0.4.1

package/lib/index.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import chokidar from "chokidar";
@@ -32,7 +33,8 @@ const Config = z.object({
 	audit: z.union(["all", "hits"]).default("all"),
 	searchUp: z.boolean().default(false),
 	maxGlobStars: z.number().default(2),
-	enforce: z.boolean().default(true)
+	enforce: z.boolean().default(true),
+	allowUnmarkedAudit: z.boolean().default(false)
 });
 /**
 * Validate raw values and fill explicit defaults. A `maxRules`,
@@ -70,6 +72,7 @@ function resolveConfig(config = {}) {
 	assertBoolean("searchUp", searchUp);
 	assertBoolean("caseInsensitivePaths", config.caseInsensitivePaths ?? process.platform === "win32");
 	assertBoolean("enforce", config.enforce ?? true);
+	assertBoolean("allowUnmarkedAudit", config.allowUnmarkedAudit ?? false);
 	return {
 		rulesFile,
 		fallbackPath: config.fallbackPath,
@@ -84,7 +87,8 @@ function resolveConfig(config = {}) {
 		audit: config.audit ?? "all",
 		searchUp,
 		maxGlobStars,
-		enforce: config.enforce ?? true
+		enforce: config.enforce ?? true,
+		allowUnmarkedAudit: config.allowUnmarkedAudit ?? false
 	};
 }
 /** Throw unless `key` is one of `allowed` (TypeScript's closed enums are not runtime checks). */
@@ -563,12 +567,16 @@ function isCatchAll(rule) {
 /**
 * One-line human summary of a compiled rule, for `/rules` output. The
 * 1-based number, action, match dimensions, and reason render first; a
-* disabled marker, tags, and a truncated description follow.
+* disabled marker, tags, and a truncated description follow. When `source`
+* is provided (multi-file chains), the rule's origin file is attributed on
+* the line.
 * @param rule - the compiled rule.
 * @param tokens - dimension-prefix vocabulary for the configured language.
+* @param source - display path of the rule's source file, when the listing
+*   spans several files.
 * @returns a single display line.
 */
-function describeRule(rule, tokens) {
+function describeRule(rule, tokens, source) {
 	const parts = [];
 	if (rule.source.match.tools.length > 0) parts.push(`${tokens.tools}:${rule.source.match.tools.join(",")}`);
 	if (rule.source.match.agents.length > 0) parts.push(`${tokens.agents}:${rule.source.match.agents.join(",")}`);
@@ -581,9 +589,10 @@ function describeRule(rule, tokens) {
 	if (whenParts.length > 0 || platformPart.length > 0) parts.push(`${tokens.when}:${whenParts}${whenParts.length > 0 && platformPart.length > 0 ? " " : ""}${platformPart}`);
 	const match = parts.length > 0 ? `[${parts.join(" ")}]` : `[${tokens.allTools}]`;
 	const disabled = rule.enabled ? "" : ` (${tokens.disabled})`;
+	const sourcePart = source !== void 0 && source.length > 0 ? ` [${tokens.src}:${source}]` : "";
 	const description = rule.description !== void 0 ? ` (${truncate(rule.description, DISPLAY_TRUNCATE)})` : "";
 	const tags = rule.tags.length > 0 ? ` [${tokens.tags}:${rule.tags.join(",")}]` : "";
-	return `${rule.index + 1}. ${rule.action}${disabled} ${match}: ${truncate(rule.reason, DISPLAY_TRUNCATE)}${description}${tags}`;
+	return `${rule.index + 1}. ${rule.action}${disabled} ${match}${sourcePart}: ${truncate(rule.reason, DISPLAY_TRUNCATE)}${description}${tags}`;
 }
 /** Cut a display string at `limit` characters, marking truncation with `…`. */
 function truncate(text, limit) {
@@ -926,9 +935,10 @@ const EN = {
 	lastReloadWarning: (error) => `Warning: the last reload failed (${error}); the rules listed above are the previous ones.`,
 	dryRunNotice: "Dry-run mode (enforce: false): deny/ask hits are audit-logged only — every call is passed through.",
 	unknownArg: (arg) => `Unknown /rules argument "${arg}". ${EN.usage}`,
-	usage: "Usage: /rules [reload | decisions [n] | test <tool> <json-args>]",
+	usage: "Usage: /rules [list | reload | decisions [n] | test <tool> <json-args>]",
 	decisionsHeader: (shown, total) => `Last ${shown} of ${total} permission decision(s) for this session:`,
 	noDecisions: "No permission decisions recorded in this session yet.",
+	auditDisabledNotice: "Session-log audit is disabled on this host: its Session.append predates the ignorable marker and would make sessions unresumable elsewhere (set allowUnmarkedAudit: true to opt back in).",
 	invalidDecisionsCount: (arg) => `Invalid decisions count "${arg}": give a positive integer (default 10).`,
 	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
 		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (rule ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (dry-run)" : ` (dry-run → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
@@ -938,7 +948,8 @@ const EN = {
 	testBadJson: (text) => `Invalid JSON arguments "${text}": the arguments must parse as JSON.`,
 	testUnknownFlag: (flag) => `Unknown /rules test flag "${flag}". ${EN.testUsage}`,
 	testBadFlag: (flag) => `Invalid /rules test flag "${flag}": expected a value. ${EN.testUsage}`,
-	testUsage: "Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... <tool> <json-args>, e.g. /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `Unknown platform "${value}" in --platform: expected one of aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${EN.testUsage}`,
+	testUsage: "Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... [--platform <name>] <tool> <json-args>, e.g. /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `Warning: rule${numbers.length > 1 ? "s" : ""} ${numbers.join(", ")} ${numbers.length > 1 ? "are" : "is"} unreachable (shadowed by an earlier catch-all rule).`,
 	emptySource: "(no rule file — empty rule set)"
 };
@@ -951,9 +962,10 @@ const ZH = {
 	lastReloadWarning: (error) => `警告：上次重载失败（${error}）；以上列出的是之前的规则。`,
 	dryRunNotice: "干跑模式（enforce: false）：deny/ask 命中仅写入审计日志——所有调用照常透传。",
 	unknownArg: (arg) => `未知的 /rules 参数 "${arg}"。${ZH.usage}`,
-	usage: "用法：/rules [reload | decisions [n] | test <工具名> <json-参数>]",
+	usage: "用法：/rules [list | reload | decisions [n] | test <工具名> <json-参数>]",
 	decisionsHeader: (shown, total) => `本会话最近 ${shown}/${total} 条权限裁决：`,
 	noDecisions: "本会话还没有记录任何权限裁决。",
+	auditDisabledNotice: "本宿主上会话日志审计已停用：其 Session.append 早于 ignorable 标记支持，会令会话在其他宿主上无法恢复（设 allowUnmarkedAudit: true 可重新开启）。",
 	invalidDecisionsCount: (arg) => `无效的裁决条数 "${arg}"：请给正整数（默认 10）。`,
 	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
 		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : `（规则 ${ruleIndex + 1}）`}${dryRun ? outcome === void 0 ? "（干跑）" : `（干跑 → ${outcome}）` : ""}${reason === void 0 ? "" : `：${short(reason)}`}`;
@@ -963,7 +975,8 @@ const ZH = {
 	testBadJson: (text) => `无效的 JSON 参数 "${text}"：参数必须能被解析为 JSON。`,
 	testUnknownFlag: (flag) => `未知的 /rules test 标志 "${flag}"。${ZH.testUsage}`,
 	testBadFlag: (flag) => `无效的 /rules test 标志 "${flag}"：缺少取值。${ZH.testUsage}`,
-	testUsage: "用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... <工具名> <json-参数>，例如 /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `未知的平台 "${value}"（--platform）：应为 aix、android、darwin、freebsd、linux、openbsd、sunos、win32 之一。${ZH.testUsage}`,
+	testUsage: "用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... [--platform <平台名>] <工具名> <json-参数>，例如 /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `警告：规则 ${numbers.join("、")} 不可达（被前面的通配规则遮蔽）。`,
 	emptySource: "（无规则文件——空规则集）"
 };
@@ -976,9 +989,10 @@ const ES = {
 	lastReloadWarning: (error) => `Aviso: la última recarga falló (${error}); las reglas mostradas son las anteriores.`,
 	dryRunNotice: "Modo simulación (enforce: false): los aciertos deny/ask solo se registran en auditoría — todas las llamadas pasan.",
 	unknownArg: (arg) => `Argumento de /rules desconocido "${arg}". ${ES.usage}`,
-	usage: "Uso: /rules [reload | decisions [n] | test <herramienta> <json-args>]",
+	usage: "Uso: /rules [list | reload | decisions [n] | test <herramienta> <json-args>]",
 	decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisión(es) de permiso de esta sesión:`,
 	noDecisions: "Esta sesión aún no registra decisiones de permiso.",
+	auditDisabledNotice: "La auditoría del registro de sesión está desactivada en este host: su Session.append es anterior al marcador ignorable y haría las sesiones irrecuperables en otros hosts (establece allowUnmarkedAudit: true para reactivarla).",
 	invalidDecisionsCount: (arg) => `Cantidad de decisiones inválida "${arg}": indique un entero positivo (por defecto 10).`,
 	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
 		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (regla ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (simulación)" : ` (simulación → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
@@ -988,7 +1002,8 @@ const ES = {
 	testBadJson: (text) => `Argumentos JSON inválidos "${text}": los argumentos deben poderse analizar como JSON.`,
 	testUnknownFlag: (flag) => `Bandera de /rules test desconocida "${flag}". ${ES.testUsage}`,
 	testBadFlag: (flag) => `Bandera de /rules test inválida "${flag}": falta un valor. ${ES.testUsage}`,
-	testUsage: "Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... <herramienta> <json-args>, p. ej. /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `Plataforma desconocida "${value}" en --platform: se esperaba una de aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${ES.testUsage}`,
+	testUsage: "Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... [--platform <nombre>] <herramienta> <json-args>, p. ej. /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `Aviso: ${numbers.length > 1 ? "las reglas" : "la regla"} ${numbers.join(", ")} ${numbers.length > 1 ? "son inalcanzables" : "es inalcanzable"} (tapada por una regla general anterior).`,
 	emptySource: "(sin archivo de reglas — conjunto vacío)"
 };
@@ -1001,9 +1016,10 @@ const PT = {
 	lastReloadWarning: (error) => `Aviso: a última recarga falhou (${error}); as regras listadas são as anteriores.`,
 	dryRunNotice: "Modo simulação (enforce: false): acertos deny/ask são apenas registrados na auditoria — todas as chamadas passam.",
 	unknownArg: (arg) => `Argumento de /rules desconhecido "${arg}". ${PT.usage}`,
-	usage: "Uso: /rules [reload | decisions [n] | test <ferramenta> <json-args>]",
+	usage: "Uso: /rules [list | reload | decisions [n] | test <ferramenta> <json-args>]",
 	decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisão(ões) de permissão desta sessão:`,
 	noDecisions: "Esta sessão ainda não registrou decisões de permissão.",
+	auditDisabledNotice: "A auditoria do registro da sessão está desativada neste host: seu Session.append é anterior ao marcador ignorable e tornaria as sessões irrecuperáveis em outros hosts (defina allowUnmarkedAudit: true para reativar).",
 	invalidDecisionsCount: (arg) => `Quantidade de decisões inválida "${arg}": informe um inteiro positivo (padrão 10).`,
 	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
 		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (regra ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (simulação)" : ` (simulação → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
@@ -1013,7 +1029,8 @@ const PT = {
 	testBadJson: (text) => `Argumentos JSON inválidos "${text}": os argumentos precisam ser JSON analisável.`,
 	testUnknownFlag: (flag) => `Sinalizador de /rules test desconhecido "${flag}". ${PT.testUsage}`,
 	testBadFlag: (flag) => `Sinalizador de /rules test inválido "${flag}": falta um valor. ${PT.testUsage}`,
-	testUsage: "Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... <ferramenta> <json-args>, ex.: /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `Plataforma desconhecida "${value}" em --platform: esperava-se uma de aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${PT.testUsage}`,
+	testUsage: "Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... [--platform <nome>] <ferramenta> <json-args>, ex.: /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `Aviso: ${numbers.length > 1 ? "as regras" : "a regra"} ${numbers.join(", ")} ${numbers.length > 1 ? "são inalcançáveis" : "é inalcançável"} (encoberta por uma regra geral anterior).`,
 	emptySource: "(sem arquivo de regras — conjunto vazio)"
 };
@@ -1026,9 +1043,10 @@ const HI = {
 	lastReloadWarning: (error) => `चेतावनी: अंतिम पुनः लोड विफल रहा (${error}); ऊपर सूचीबद्ध नियम पिछले वाले हैं।`,
 	dryRunNotice: "ड्राई-रन मोड (enforce: false): deny/ask हिट केवल ऑडिट में दर्ज होते हैं — हर कॉल पास हो जाती है।",
 	unknownArg: (arg) => `अज्ञात /rules तर्क "${arg}"। ${HI.usage}`,
-	usage: "उपयोग: /rules [reload | decisions [n] | test <टूल> <json-args>]",
+	usage: "उपयोग: /rules [list | reload | decisions [n] | test <टूल> <json-args>]",
 	decisionsHeader: (shown, total) => `इस सत्र के अंतिम ${shown}/${total} अनुमति निर्णय:`,
 	noDecisions: "इस सत्र में अभी कोई अनुमति निर्णय दर्ज नहीं है।",
+	auditDisabledNotice: "इस होस्ट पर सत्र-लॉग ऑडिट अक्षम है: इसका Session.append ignorable मार्कर से पुराना है और सत्र अन्य होस्ट पर अप्राप्य बन जाते (पुनः चालू करने के लिए allowUnmarkedAudit: true सेट करें)।",
 	invalidDecisionsCount: (arg) => `अमान्य निर्णय-संख्या "${arg}": एक धनात्मक पूर्णांक दें (डिफ़ॉल्ट 10)।`,
 	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
 		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (नियम ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (ड्राई-रन)" : ` (ड्राई-रन → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
@@ -1038,7 +1056,8 @@ const HI = {
 	testBadJson: (text) => `अमान्य JSON तर्क "${text}": तर्क JSON के रूप में पार्स होने चाहिए।`,
 	testUnknownFlag: (flag) => `अज्ञात /rules test फ़्लैग "${flag}"। ${HI.testUsage}`,
 	testBadFlag: (flag) => `अमान्य /rules test फ़्लैग "${flag}": मान गायब है। ${HI.testUsage}`,
-	testUsage: "उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... <टूल> <json-args>, जैसे /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `अज्ञात प्लेटफ़ॉर्म "${value}" (--platform): aix, android, darwin, freebsd, linux, openbsd, sunos, win32 में से एक अपेक्षित। ${HI.testUsage}`,
+	testUsage: "उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... [--platform <नाम>] <टूल> <json-args>, जैसे /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `चेतावनी: नियम ${numbers.join(", ")} अप्राप्य हैं (पहले वाले सर्व-मिलान नियम से ढके हुए)।`,
 	emptySource: "(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)"
 };
@@ -1062,7 +1081,8 @@ const DESCRIBE_TOKENS = {
 		when: "when",
 		platform: "platform",
 		disabled: "disabled",
-		tags: "tags"
+		tags: "tags",
+		src: "src"
 	},
 	zh: {
 		allTools: "全部工具",
@@ -1074,7 +1094,8 @@ const DESCRIBE_TOKENS = {
 		when: "条件",
 		platform: "平台",
 		disabled: "已禁用",
-		tags: "标签"
+		tags: "标签",
+		src: "来源"
 	},
 	es: {
 		allTools: "todas las herramientas",
@@ -1086,7 +1107,8 @@ const DESCRIBE_TOKENS = {
 		when: "cuándo",
 		platform: "plataforma",
 		disabled: "deshabilitada",
-		tags: "etiquetas"
+		tags: "etiquetas",
+		src: "origen"
 	},
 	pt: {
 		allTools: "todas as ferramentas",
@@ -1098,7 +1120,8 @@ const DESCRIBE_TOKENS = {
 		when: "quando",
 		platform: "plataforma",
 		disabled: "desativada",
-		tags: "etiquetas"
+		tags: "etiquetas",
+		src: "origem"
 	},
 	hi: {
 		allTools: "सभी टूल",
@@ -1110,10 +1133,25 @@ const DESCRIBE_TOKENS = {
 		when: "शर्त",
 		platform: "प्लेटफ़ॉर्म",
 		disabled: "अक्षम",
-		tags: "टैग"
+		tags: "टैग",
+		src: "स्रोत"
 	}
 };
 //#endregion
+//#region src/events.ts
+/**
+* Whether an `append` call actually honored the `ignorable` marker: the
+* logged event returned by the host carries `ignorable === true` on
+* marker-aware builds and nothing on pre-marker builds. `false` (or any
+* non-event return) means the host dropped the marker and the event landed
+* unmarked — the runtime then degrades instead of polluting further logs.
+* @param result - the return value of the audit append.
+* @returns true only when the marker is present on the returned envelope.
+*/
+function isMarkedAuditEvent(result) {
+	return typeof result === "object" && result !== null && result.ignorable === true;
+}
+//#endregion
 //#region src/runtime.ts
 /**
 * Runtime of `dsh-permission-rules`: per-workspace rule loading (project
@@ -1122,7 +1160,9 @@ const DESCRIBE_TOKENS = {
 * deny/ask decision (and NEVER short-circuits on allow or passthrough),
 * the `permissionRules/decision` audit event, the `/rules` session command
 * (`list | reload | decisions [n] | test [flags] <tool> <json>`), and
-* Chokidar-driven reloads. Every registration is an effect.
+* Chokidar-driven reloads (effective rule files plus candidate watches on
+* expected-but-absent files, so mid-session creation is adopted). Every
+* registration is an effect.
 * @module dsh-permission-rules/runtime
 */
 /**
@@ -1134,10 +1174,12 @@ var PermissionRulesRuntime = class {
 	config;
 	/** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
 	byCwd = /* @__PURE__ */ new Map();
-	/** Live watchers per rule-file path, with the cwds each serves. */
+	/** Live watchers per watched path (rule file or candidate ancestor directory), with the cwds each serves. */
 	watchers = /* @__PURE__ */ new Map();
 	/** Debounce timers per rule-file path. */
 	timers = /* @__PURE__ */ new Map();
+	/** Whether the host honors the audit envelope's `ignorable` marker: unknown until the first decision (or peer-version check). */
+	auditSupport = "unknown";
 	constructor(ctx, config) {
 		this.ctx = ctx;
 		this.config = config;
@@ -1232,6 +1274,17 @@ var PermissionRulesRuntime = class {
 		}
 	}
 	/**
+	* Canonical per-workspace cache key: the resolved root, case-folded on
+	* Windows so differently-spelled paths to the same workspace share one
+	* cache entry and one watcher set instead of doubling both.
+	* @param cwd - the session's absolute workspace root.
+	* @returns the canonical key.
+	*/
+	cacheKey(cwd) {
+		const resolved = resolve(cwd);
+		return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	}
+	/**
 	* The rules in effect for one cwd, loading on first use. Under
 	* `badFilePolicy: 'fail'` a bad initial load throws on EVERY use (the
 	* pending tool call errors loudly) while the watcher keeps observing the
@@ -1242,23 +1295,24 @@ var PermissionRulesRuntime = class {
 	* @returns the loaded rules.
 	*/
 	rulesFor(cwd) {
-		const existing = this.byCwd.get(cwd);
+		const key = this.cacheKey(cwd);
+		const existing = this.byCwd.get(key);
 		if (existing !== void 0) {
 			if (existing.failed === true) throw new RuleError(existing.lastError ?? `rule load failed for ${cwd}`);
-			this.byCwd.delete(cwd);
-			this.byCwd.set(cwd, existing);
+			this.byCwd.delete(key);
+			this.byCwd.set(key, existing);
 			return existing;
 		}
-		this.evictIfFull(cwd);
+		this.evictIfFull(key);
 		try {
 			const loaded = this.load(cwd);
-			this.byCwd.set(cwd, loaded);
-			this.reconcileWatch(cwd, loaded.sources);
+			this.byCwd.set(key, loaded);
+			this.reconcileWatch(key, loaded.sources);
 			return loaded;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			const sources = this.resolveSources(cwd);
-			this.byCwd.set(cwd, {
+			this.byCwd.set(key, {
 				cwd,
 				sources,
 				compiled: {
@@ -1268,7 +1322,7 @@ var PermissionRulesRuntime = class {
 				lastError: message,
 				failed: true
 			});
-			this.reconcileWatch(cwd, sources);
+			this.reconcileWatch(key, sources);
 			throw error;
 		}
 	}
@@ -1280,29 +1334,34 @@ var PermissionRulesRuntime = class {
 	* @param cwd - the workspace root.
 	*/
 	reload(cwd) {
-		const previous = this.byCwd.get(cwd);
+		const key = this.cacheKey(cwd);
+		const previous = this.byCwd.get(key);
 		try {
 			const loaded = this.load(cwd);
-			this.byCwd.set(cwd, loaded);
-			this.reconcileWatch(cwd, loaded.sources);
+			this.byCwd.set(key, loaded);
+			this.reconcileWatch(key, loaded.sources);
 			this.ctx.logger.info(`permission-rules: reloaded ${loaded.compiled.rules.length} rule(s) from ${loaded.sources.join(", ") || "(empty rule set)"} for ${cwd}`);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			this.ctx.logger.warn(`permission-rules: reload failed for ${cwd}: ${message} (keeping previous rules)`);
-			if (previous !== void 0) this.byCwd.set(cwd, {
+			if (previous !== void 0) this.byCwd.set(key, {
 				...previous,
 				lastError: message
 			});
-			else this.byCwd.set(cwd, {
-				cwd,
-				sources: this.resolveSources(cwd),
-				compiled: {
-					rules: [],
-					caseInsensitivePaths: this.config.caseInsensitivePaths
-				},
-				lastError: message,
-				failed: true
-			});
+			else {
+				const sources = this.resolveSources(cwd);
+				this.byCwd.set(key, {
+					cwd,
+					sources,
+					compiled: {
+						rules: [],
+						caseInsensitivePaths: this.config.caseInsensitivePaths
+					},
+					lastError: message,
+					failed: true
+				});
+				this.reconcileWatch(key, sources);
+			}
 		}
 	}
 	/**
@@ -1361,13 +1420,17 @@ var PermissionRulesRuntime = class {
 	* Append the log-only `permissionRules/decision` audit event for every
 	* decision (passthrough included unless `audit: 'hits'`), requesting the
 	* envelope's `ignorable: true` marker so any harness build can load the
-	* log (readers that do not know the type skip the audit record instead of
-	* refusing the session). `source` names the matched rule's file, or the
-	* nearest effective file on a passthrough; `cwd` names the workspace the
-	* rules were resolved for; `dryRun` marks would-be deny/ask hits under
-	* `enforce: false`. Agentless calls have no session to audit; append
-	* failures are contained so an audit hiccup can never change a
-	* permission decision.
+	* log. Hosts whose `Session.append` predates the marker (the rc.6 line)
+	* silently drop it, leaving sessions unresumable on stricter hosts — the
+	* runtime therefore detects such hosts BEFORE the first append (peer
+	* version) and re-checks after the first append (returned envelope), then
+	* degrades: session-log audit is disabled with a one-time warning unless
+	* `allowUnmarkedAudit: true` opts back in. `source` names the matched
+	* rule's file, or the nearest effective file on a passthrough; `cwd`
+	* names the workspace the rules were resolved for; `dryRun` marks
+	* would-be deny/ask hits under `enforce: false`. Agentless calls have no
+	* session to audit; append failures are contained so an audit hiccup can
+	* never change a permission decision.
 	* @param exec - the pending call.
 	* @param loaded - the rules in effect.
 	* @param hit - the first matching rule, or undefined for passthrough.
@@ -1378,8 +1441,17 @@ var PermissionRulesRuntime = class {
 		if (this.config.audit === "hits" && hit === void 0) return;
 		const agent = exec.agent;
 		if (agent === void 0) return;
+		if (this.auditSupport === "unsupported") return;
+		if (this.auditSupport === "unknown" && !this.config.allowUnmarkedAudit) {
+			const version = this.peerVersion();
+			if (version !== null && isUnmarkedHostVersion(version)) {
+				this.auditSupport = "unsupported";
+				this.warnUnmarkedAuditHost();
+				return;
+			}
+		}
 		try {
-			agent.session.append("permissionRules/decision", {
+			const result = this.appendAudit(agent, {
 				toolName: exec.name,
 				callId: exec.callId,
 				source: hit === void 0 ? loaded.sources[0] ?? "" : loaded.sources[hit.rule.sourceIndex] ?? "",
@@ -1391,11 +1463,35 @@ var PermissionRulesRuntime = class {
 					reason: hit.rule.reason
 				} : {},
 				...dryRun ? { dryRun: true } : {}
-			}, { ignorable: true });
+			});
+			if (this.auditSupport === "unknown" && !this.config.allowUnmarkedAudit) {
+				if (isMarkedAuditEvent(result)) this.auditSupport = "supported";
+				else {
+					this.auditSupport = "unsupported";
+					this.warnUnmarkedAuditHost();
+				}
+			}
 		} catch (error) {
 			this.ctx.logger.warn(`permission-rules: audit append failed: ${String(error)}`);
 		}
 	}
+	/** Append one audit event through the session surface; the probe seam for host-capability detection. */
+	appendAudit(agent, data) {
+		return agent.session.append("permissionRules/decision", data, { ignorable: true });
+	}
+	/** The installed `@deepseek-ai/dsh-session` version, or `null` when unresolvable (falls back to the append probe). */
+	peerVersion() {
+		try {
+			const pkg = createRequire(import.meta.url)("@deepseek-ai/dsh-session/package.json");
+			return typeof pkg.version === "string" ? pkg.version : null;
+		} catch {
+			return null;
+		}
+	}
+	/** One-time warning that session-log audit was disabled to keep session logs loadable. */
+	warnUnmarkedAuditHost() {
+		this.ctx.logger.warn("permission-rules: this host drops the ignorable marker on audit events (Session.append predates it), which would make sessions unresumable on stricter harness builds — session-log audit is disabled; set allowUnmarkedAudit: true to opt back in, and repair existing logs with scripts/repair-session-logs.mjs (see https://github.com/PerryLink/dsh-permission-rules/issues/2)");
+	}
 	/**
 	* Execute the `/rules` command: bare `/rules` lists the active rules and
 	* their sources; `/rules reload` re-reads the chain; `/rules decisions
@@ -1418,7 +1514,7 @@ var PermissionRulesRuntime = class {
 				text: prose.unknownArg(invocation.rawInput.trim())
 			};
 			this.reload(cwd);
-			const reloaded = this.byCwd.get(cwd);
+			const reloaded = this.byCwd.get(this.cacheKey(cwd));
 			if (reloaded?.lastError !== void 0) return {
 				kind: "error",
 				text: prose.reloadFailed(reloaded.lastError)
@@ -1430,6 +1526,10 @@ var PermissionRulesRuntime = class {
 				text: prose.reloaded(rules.length, source)
 			};
 		}
+		if (verb === "list" && rest.length > 0) return {
+			kind: "error",
+			text: prose.unknownArg(invocation.rawInput.trim())
+		};
 		if (verb === "decisions") {
 			if (rest.length > 1) return {
 				kind: "error",
@@ -1447,7 +1547,7 @@ var PermissionRulesRuntime = class {
 			return this.decisionsCommand(invocation, count, prose);
 		}
 		if (verb === "test") return this.testCommand(raw, verbRaw ?? "", invocation, cwd, prose);
-		if (verb !== "") return {
+		if (verb !== "" && verb !== "list") return {
 			kind: "error",
 			text: prose.unknownArg(invocation.rawInput.trim())
 		};
@@ -1464,7 +1564,8 @@ var PermissionRulesRuntime = class {
 		if (loaded.sources.length === 0) lines.push(prose.noRules(cwd, this.config.fallbackPath !== void 0 ? prose.fallbackMissing : ""));
 		else {
 			lines.push(prose.rulesHeader(loaded.compiled.rules.length, loaded.sources, cwd));
-			lines.push(...loaded.compiled.rules.map((rule) => describeRule(rule, DESCRIBE_TOKENS[this.config.language])));
+			const multiSource = loaded.sources.length > 1;
+			lines.push(...loaded.compiled.rules.map((rule) => describeRule(rule, DESCRIBE_TOKENS[this.config.language], multiSource ? this.displaySource(loaded.sources[rule.sourceIndex] ?? "", cwd) : void 0)));
 			const unreachable = findUnreachableRules(loaded.compiled);
 			if (unreachable.length > 0) lines.push(prose.unreachableWarning(unreachable.map((index) => index + 1)));
 		}
@@ -1480,9 +1581,11 @@ var PermissionRulesRuntime = class {
 	* Execute `/rules test` with optional leading flags: `--cwd <dir>`
 	* evaluates against that workspace (rule discovery AND path
 	* normalization), `--env KEY=VALUE` (repeatable) overrides host env for
-	* `when.env` matching, and `--agent <selector>` (repeatable) supplies
-	* agent-identity candidates for the `agents` dimension. The JSON
-	* argument tail is kept verbatim, so quoted JSON survives unchanged.
+	* `when.env` matching, `--agent <selector>` (repeatable) supplies
+	* agent-identity candidates for the `agents` dimension, and
+	* `--platform <name>` overrides the host platform for `when.platform`.
+	* The JSON argument tail is kept verbatim, so quoted JSON survives
+	* unchanged.
 	* @param raw - the full raw command input.
 	* @param verbRaw - the verb as typed.
 	* @param invocation - the received command invocation (session agent).
@@ -1495,6 +1598,7 @@ var PermissionRulesRuntime = class {
 		const envOverrides = {};
 		const agentSelectors = [];
 		let testCwd;
+		let testPlatform;
 		let parsed = nextToken(rest);
 		while (parsed !== void 0 && parsed.token.startsWith("--")) {
 			const flag = parsed.token;
@@ -1512,7 +1616,13 @@ var PermissionRulesRuntime = class {
 				};
 				envOverrides[value.token.slice(0, equals)] = value.token.slice(equals + 1);
 			} else if (flag === "--agent") agentSelectors.push(value.token);
-			else return {
+			else if (flag === "--platform") {
+				if (!PLATFORMS.includes(value.token)) return {
+					kind: "error",
+					text: prose.testBadPlatform(value.token)
+				};
+				testPlatform = value.token;
+			} else return {
 				kind: "error",
 				text: prose.testUnknownFlag(flag)
 			};
@@ -1545,7 +1655,7 @@ var PermissionRulesRuntime = class {
 			};
 		}
 		const context = {
-			platform: process.platform,
+			platform: testPlatform ?? process.platform,
 			env: Object.keys(envOverrides).length === 0 ? process.env : {
 				...process.env,
 				...envOverrides
@@ -1558,19 +1668,26 @@ var PermissionRulesRuntime = class {
 			text: hit === void 0 ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason)
 		};
 	}
+	/** Render one rule-file source for per-rule attribution: workspace-relative when inside the cwd, raw otherwise. */
+	displaySource(source, cwd) {
+		if (source.length === 0) return "";
+		const relative = normalizeWorkspacePath(cwd, source, this.config.caseInsensitivePaths);
+		return relative.length > 0 ? relative : source;
+	}
 	/** Render the session's `permissionRules/decision` audit trail, newest last. */
 	decisionsCommand(invocation, count, prose) {
 		const decisions = invocation.agent.session.events.filter((event) => event.type === "permissionRules/decision");
-		if (decisions.length === 0) return {
-			kind: "success",
-			text: prose.noDecisions
-		};
-		const shown = decisions.slice(-count);
-		const lines = [prose.decisionsHeader(shown.length, decisions.length)];
-		for (const event of shown) {
-			const data = event.data;
-			lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason, data.dryRun === true, data.outcome));
+		const lines = [];
+		if (decisions.length === 0) lines.push(prose.noDecisions);
+		else {
+			const shown = decisions.slice(-count);
+			lines.push(prose.decisionsHeader(shown.length, decisions.length));
+			for (const event of shown) {
+				const data = event.data;
+				lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason, data.dryRun === true, data.outcome));
+			}
 		}
+		if (this.auditSupport === "unsupported") lines.push(prose.auditDisabledNotice);
 		return {
 			kind: "success",
 			text: lines.join("\n")
@@ -1642,16 +1759,97 @@ var PermissionRulesRuntime = class {
 	* Rebind `cwd` to its current rule-source chain. When a concrete source
 	* left the chain (deleted file, fallback switch), detach the workspace
 	* from watchers serving other sources and close the ones left empty, so
-	* long-running hosts cannot accumulate stale watchers. An empty chain (no
-	* rule file in effect) keeps the previous watchers alive: they own the
-	* "file recreated → adopted" signal, and the workspace-cache bound keeps
-	* the set of such watchers finite.
+	* long-running hosts cannot accumulate stale watchers. Expected-but-absent
+	* rule files (the project file when it is not effective, and a configured
+	* fallback that does not exist) are covered by candidate watchers on
+	* their deepest existing ancestor directory, so a file created
+	* mid-session is adopted without a manual `/rules reload`. With
+	* `searchUp`, only the immediate cwd-level candidate is watched —
+	* deeper ancestors are discovered on the next load.
 	*/
 	reconcileWatch(cwd, sources) {
-		if (sources.length === 0) return;
-		for (const [watchedSource, entry] of this.watchers) if (!sources.includes(watchedSource)) entry.cwds.delete(cwd);
+		for (const [watchedSource, entry] of this.watchers) if (!sources.includes(watchedSource)) {
+			entry.cwds.delete(cwd);
+			entry.candidates?.delete(cwd);
+		}
 		this.pruneWatchers();
 		for (const source of sources) this.attachWatch(cwd, source);
+		for (const candidate of this.candidateSources(cwd)) {
+			if (sources.includes(candidate) || existsSync(candidate)) continue;
+			this.attachCandidateWatch(cwd, candidate);
+		}
+	}
+	/**
+	* The rule-file paths a workspace COULD be served by: the project file
+	* (an absolute `rulesFile`, or `<cwd>/<rulesFile>` — the immediate level
+	* only under `searchUp`) plus the configured fallback.
+	*/
+	candidateSources(cwd) {
+		const candidates = [isAbsolute(this.config.rulesFile) ? this.config.rulesFile : join(cwd, this.config.rulesFile)];
+		const fallback = this.config.fallbackPath;
+		if (fallback !== void 0) candidates.push(isAbsolute(fallback) ? fallback : resolve(fallback));
+		return candidates;
+	}
+	/**
+	* Watch one expected-but-absent rule file through its deepest existing
+	* ancestor directory. Chokidar cannot reliably watch a missing path when
+	* its parent is also missing, but directory watching is dependable; every
+	* relevant event re-checks existence and only triggers a reload once the
+	* candidate actually appeared, so unrelated workspace activity while the
+	* file is absent costs a stat, not a reload.
+	*/
+	attachCandidateWatch(cwd, candidate) {
+		if (!this.config.watch) return;
+		const dir = this.deepestExistingDir(dirname(candidate));
+		const existing = this.watchers.get(dir);
+		if (existing !== void 0) {
+			existing.cwds.add(cwd);
+			existing.candidates?.set(cwd, candidate);
+			return;
+		}
+		const cwds = /* @__PURE__ */ new Set([cwd]);
+		const candidates = /* @__PURE__ */ new Map([[cwd, candidate]]);
+		const watcher = chokidar.watch(dir, {
+			persistent: true,
+			ignoreInitial: true
+		});
+		const onEvent = () => this.scheduleReload(dir);
+		watcher.on("add", onEvent);
+		watcher.on("addDir", onEvent);
+		watcher.on("change", onEvent);
+		watcher.on("unlink", onEvent);
+		watcher.on("unlinkDir", onEvent);
+		watcher.on("error", (error) => {
+			this.ctx.logger.warn(`permission-rules: watcher error on ${dir}: ${String(error)}`);
+		});
+		this.watchers.set(dir, {
+			cwds,
+			candidates,
+			close: () => {
+				watcher.close().catch((error) => {
+					this.ctx.logger.warn(`permission-rules: failed to close watcher on ${dir}: ${String(error)}`);
+				});
+			}
+		});
+		this.ctx.effect(() => () => {
+			this.watchers.get(dir)?.close();
+			this.watchers.delete(dir);
+			const timer = this.timers.get(dir);
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				this.timers.delete(dir);
+			}
+		});
+	}
+	/** The deepest existing ancestor directory of `dir` (candidate watchers target directories, never missing files). */
+	deepestExistingDir(dir) {
+		let current = dir;
+		for (;;) {
+			if (existsSync(current)) return current;
+			const parent = dirname(current);
+			if (parent === current) return current;
+			current = parent;
+		}
 	}
 	/** Close and drop watchers whose workspace sets are empty, clearing their debounce timers. */
 	pruneWatchers() {
@@ -1678,7 +1876,10 @@ var PermissionRulesRuntime = class {
 		const oldest = this.byCwd.keys().next().value;
 		if (oldest === void 0) return;
 		this.byCwd.delete(oldest);
-		for (const entry of this.watchers.values()) entry.cwds.delete(oldest);
+		for (const entry of this.watchers.values()) {
+			entry.cwds.delete(oldest);
+			entry.candidates?.delete(oldest);
+		}
 		this.pruneWatchers();
 	}
 	/** Number of live watchers, for observability and tests. */
@@ -1689,13 +1890,24 @@ var PermissionRulesRuntime = class {
 	pendingReloadCount() {
 		return this.timers.size;
 	}
-	/** Debounce watch events into one reload per stability window. */
+	/**
+	* Debounce watch events into one reload per stability window. A
+	* candidate (directory) watcher only reloads a cwd once its expected
+	* file actually exists — unrelated events while the file is absent are
+	* dropped before any re-read.
+	*/
 	scheduleReload(source) {
 		const existing = this.timers.get(source);
 		if (existing !== void 0) clearTimeout(existing);
 		const timer = setTimeout(() => {
 			this.timers.delete(source);
-			for (const cwd of this.watchers.get(source)?.cwds ?? []) this.reload(cwd);
+			const entry = this.watchers.get(source);
+			if (entry === void 0) return;
+			for (const cwd of entry.cwds) {
+				const candidate = entry.candidates?.get(cwd);
+				if (candidate !== void 0 && !existsSync(candidate)) continue;
+				this.reload(cwd);
+			}
 		}, this.config.watchStabilityThresholdMs);
 		this.timers.set(source, timer);
 	}
@@ -1714,11 +1926,26 @@ function apply(ctx, config) {
 	ctx.commands.register({
 		name: "rules",
 		description: "list, reload, audit, or dry-test the active permission rules for this workspace",
-		input: { hint: "[reload | decisions [n] | test [--cwd <dir>] [--env K=V] [--agent <sel>] <tool> <json-args>]" },
+		input: { hint: "[list | reload | decisions [n] | test [--cwd <dir>] [--env K=V] [--agent <sel>] [--platform <name>] <tool> <json-args>]" },
 		handler: (invocation) => runtime.command(invocation)
 	});
 }
 /**
+* Whether a `@deepseek-ai/dsh-session` version line predates the
+* `ignorable` envelope-marker surface: the `0.1.0-rc.6` line and earlier
+* silently drop the marker from `Session.append` options, so audit events
+* written by those builds land unmarked and break resume on stricter
+* hosts. Non-matching (post-rc.6, stable, or unresolvable) versions are
+* treated as possibly-marker-aware and verified by the append probe.
+* @param version - the installed peer version string.
+* @returns true for the known-unmarked rc.1–rc.6 lines.
+*/
+function isUnmarkedHostVersion(version) {
+	const match = /^0\.1\.0-rc\.(\d+)$/.exec(version.trim());
+	if (match === null) return false;
+	return Number(match[1]) <= 6;
+}
+/**
 * Identity candidates for the `agents` match dimension, derived from the
 * caller agent's session header: `main` for top-level sessions, `subagent`
 * for subagent children (`header.origin === 'subagent'`), and
@@ -1793,4 +2020,4 @@ function nextToken(text) {
 const name = "permission-rules";
 const inject = ["commands", "tools"];
 //#endregion
-export { Config, GlobError, PATH_CANDIDATE_KEYS, PLATFORMS, PermissionRulesRuntime, RULE_ACTIONS, RuleError, apply, compileGlob, compilePatternRegex, compileRules, compileRulesChain, describeRule, extractPathCandidates, findUnreachableRules, inject, matchRules, name, normalizeWorkspacePath, parseRulesDocument, resolveConfig };
+export { Config, GlobError, PATH_CANDIDATE_KEYS, PLATFORMS, PermissionRulesRuntime, RULE_ACTIONS, RuleError, apply, compileGlob, compilePatternRegex, compileRules, compileRulesChain, describeRule, extractPathCandidates, findUnreachableRules, inject, isMarkedAuditEvent, isUnmarkedHostVersion, matchRules, name, normalizeWorkspacePath, parseRulesDocument, resolveConfig };