@namzu/cli 12.1.0 → 13.0.0

package/dist/config/schema.d.ts

@@ -1,14 +1,59 @@
 /**
- * @namzu/cli config schema (M0 stub).
+ * Public @namzu/cli configuration vocabulary.
  *
- * The schema is intentionally minimal in M0; each later milestone extends
- * it as concrete settings land (M2 providers, M4 memory, M5 skills, etc.).
- * Validation library (e.g. Zod) is introduced when constraints exist that
- * are worth enforcing at runtime — premature now.
+ * Runtime admission lives in `load.ts`, beside the source/precedence facts it
+ * needs for actionable errors. Keeping this file declarative makes the public
+ * type the one list of settings while the loader's total reader map forces a
+ * validation decision whenever that list grows.
  */
 import type { McpServersConfig } from '../integrations/mcp/servers.js';
 import type { FormatName } from '../output/index.js';
+import type { PermissionChecksConfig } from '../permissions/checks.js';
 import type { PermissionsConfig } from '../permissions/rules.js';
+/**
+ * What one profile may set.
+ *
+ * Executable plugins are intentionally excluded as well as nested profiles:
+ * `NAMZU_PROFILE` may select a declared profile, and ambient shell state must
+ * not be able to turn code loading on.
+ */
+export type ProfileConfig = Omit<NamzuCliConfig, 'profiles' | 'plugins'>;
+export type ProfilesConfig = Readonly<Record<string, ProfileConfig>>;
+/** The two operator-visible moments the TUI can notify about. */
+export type TerminalNotificationEvent = 'turn-settled' | 'approval-required';
+/** Escape protocol used for an opted-in terminal notification. */
+export type TerminalNotificationMethod = 'osc9' | 'bel';
+export interface TuiConfig {
+    /**
+     * Notify for TUI events through the terminal itself.
+     *
+     * Absent or `false` means off. `true` enables both events; a list enables
+     * only the named events, and an empty list explicitly disables all of them.
+     * No command is started and no conversation content is included.
+     */
+    readonly notifications?: boolean | readonly TerminalNotificationEvent[];
+    /** Terminal protocol to write. Defaults to `osc9` when notifications are on. */
+    readonly notificationMethod?: TerminalNotificationMethod;
+}
+/** Where the CLI may discover executable plugin bundles. */
+export type PluginScope = 'project' | 'user';
+/**
+ * Session plugin runtime settings.
+ *
+ * Plugins may import JavaScript hooks and tools, so the runtime is disabled
+ * unless an operator opts in explicitly. Project plugins are considered only
+ * after the existing project trust gate has pinned the canonical cwd.
+ */
+export interface PluginConfig {
+    /** Start the plugin runtime. Only the exact value `true` enables it. */
+    readonly enabled?: boolean;
+    /** Scan admitted plugin directories. Defaults to `true` once enabled. */
+    readonly autoDiscovery?: boolean;
+    /** Locations the discovery pass may read. Defaults to project and user. */
+    readonly allowedScopes?: readonly PluginScope[];
+    /** Per-hook deadline in milliseconds. Defaults to the SDK runtime default. */
+    readonly hookTimeoutMs?: number;
+}
 export interface NamzuCliConfig {
     /** Default output format when not overridden by --format. */
     readonly format?: FormatName;
@@ -22,6 +67,34 @@ export interface NamzuCliConfig {
      * it meant before this existed — the absence of a policy never widens one.
      */
     readonly permissions?: PermissionsConfig;
+    /**
+     * What the operator believes the table above decides, checked at startup.
+     *
+     * Each entry names a tool, an input, and the expected `"allow" | "ask" |
+     * "deny"`. A mismatch is reported by index and the run continues — the
+     * point is to say that a policy does not do what its author said, which
+     * a table of globs cannot be read for. Absent means nothing is checked,
+     * which is what it meant before this existed.
+     */
+    readonly permissionChecks?: PermissionChecksConfig;
+    /**
+     * Named bundles of settings to switch between.
+     *
+     * A profile is not another file. It sits INSIDE one, so the settings a
+     * person switches between live next to each other and can be read as a
+     * set — which is the thing a second config file cannot give you, because
+     * a second file has to be found before it can be compared.
+     *
+     * Selecting one applies it as a layer above the file it came from, so a
+     * profile overrides that file's own base values and is in turn overridden
+     * by the environment. A profile may set anything except `profiles` and
+     * executable `plugins`: a
+     * profile that carried profiles would be a cascade inside a cascade, and
+     * the question "which one is active" would stop having one answer.
+     * Plugins are excluded because `NAMZU_PROFILE` can select a profile; shell
+     * state must not be an executable-code authority.
+     */
+    readonly profiles?: ProfilesConfig;
     /**
      * External tool servers to connect, keyed by the name their tools are
      * prefixed with.
@@ -30,6 +103,8 @@ export interface NamzuCliConfig {
      * means no external servers, which is what it meant before this existed.
      */
     readonly mcpServers?: McpServersConfig;
+    /** Executable extension bundles. Absent keeps discovery and imports off. */
+    readonly plugins?: PluginConfig;
     /**
      * Isolation for the commands this CLI runs.
      *
@@ -53,6 +128,8 @@ export interface NamzuCliConfig {
      * something a default arranges.
      */
     readonly telemetry?: TelemetryConfig;
+    /** Interactive-terminal-only behaviour. Absent leaves notifications off. */
+    readonly tui?: TuiConfig;
 }
 export interface TelemetryConfig {
     /**
@@ -118,6 +195,11 @@ export interface SandboxConfig {
      * a refusal instead of a surprise.
      */
     readonly requireIsolation?: readonly ('filesystem' | 'network' | 'process')[];
+    /**
+     * How long a completed or cancelled run waits for sandbox teardown.
+     * Defaults to 30 seconds. Set to `0` to preserve the former unbounded wait.
+     */
+    readonly teardownTimeoutMs?: number;
 }
 export declare const DEFAULT_CONFIG: NamzuCliConfig;
 //# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAEhE,MAAM,WAAW,cAAc;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAA;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAA;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAA;IACtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAA;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAA;CACpC;AAED,MAAM,WAAW,eAAe;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAA;CAC5C;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;CACzD;AAED,kDAAkD;AAClD,MAAM,MAAM,yBAAyB,GAAG,SAAS,CAAA;AAEjD,MAAM,WAAW,aAAa;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,EAAE,CAAA;CAC7E;AAED,eAAO,MAAM,cAAc,EAAE,cAG3B,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}

package/dist/config/schema.js

@@ -1,10 +1,10 @@
 /**
- * @namzu/cli config schema (M0 stub).
+ * Public @namzu/cli configuration vocabulary.
  *
- * The schema is intentionally minimal in M0; each later milestone extends
- * it as concrete settings land (M2 providers, M4 memory, M5 skills, etc.).
- * Validation library (e.g. Zod) is introduced when constraints exist that
- * are worth enforcing at runtime — premature now.
+ * Runtime admission lives in `load.ts`, beside the source/precedence facts it
+ * needs for actionable errors. Keeping this file declarative makes the public
+ * type the one list of settings while the loader's total reader map forces a
+ * validation decision whenever that list grows.
  */
 export const DEFAULT_CONFIG = Object.freeze({
     format: 'text',

package/dist/config/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyHH,MAAM,CAAC,MAAM,cAAc,GAAmB,MAAM,CAAC,MAAM,CAAC;IAC3D,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,KAAK;CACZ,CAAC,CAAA"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkNH,MAAM,CAAC,MAAM,cAAc,GAAmB,MAAM,CAAC,MAAM,CAAC;IAC3D,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,KAAK;CACZ,CAAC,CAAA"}

package/dist/config/trusted-project-context.d.ts

@@ -0,0 +1,11 @@
+export declare function bindTrustedProjectContext<T extends object>(bootstrap: T, resolve: (cwd: string) => T): T;
+export declare function resolveTrustedProjectContext<T extends object>(bootstrap: T, cwd: string): T;
+/**
+ * Pin a real project path only for contexts the CLI marked as trust-aware.
+ *
+ * Embedded/hand-built contexts keep their historical lexical cwd behaviour;
+ * production bootstrap contexts cannot proceed if their target disappears
+ * while crossing the trust boundary.
+ */
+export declare function pinTrustedProjectPath(bootstrap: object, cwd: string): string;
+//# sourceMappingURL=trusted-project-context.d.ts.map

package/dist/config/trusted-project-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-project-context.d.ts","sourceRoot":"","sources":["../../src/config/trusted-project-context.ts"],"names":[],"mappings":"AAWA,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,EACzD,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GACzB,CAAC,CAGH;AAED,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAG3F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5E"}

package/dist/config/trusted-project-context.js

@@ -0,0 +1,28 @@
+import { canonicalProjectPath } from '../permissions/canonical-project.js';
+/**
+ * Internal bridge from a pre-trust context to its project-aware replacement.
+ *
+ * A WeakMap keeps this authority out of the public CommandContext/TuiContext
+ * shapes. Hand-built embedded contexts therefore retain their existing
+ * behaviour: resolving them is an identity operation.
+ */
+const trustedResolvers = new WeakMap();
+export function bindTrustedProjectContext(bootstrap, resolve) {
+    trustedResolvers.set(bootstrap, resolve);
+    return bootstrap;
+}
+export function resolveTrustedProjectContext(bootstrap, cwd) {
+    const resolve = trustedResolvers.get(bootstrap);
+    return resolve ? resolve(cwd) : bootstrap;
+}
+/**
+ * Pin a real project path only for contexts the CLI marked as trust-aware.
+ *
+ * Embedded/hand-built contexts keep their historical lexical cwd behaviour;
+ * production bootstrap contexts cannot proceed if their target disappears
+ * while crossing the trust boundary.
+ */
+export function pinTrustedProjectPath(bootstrap, cwd) {
+    return trustedResolvers.has(bootstrap) ? canonicalProjectPath(cwd) : cwd;
+}
+//# sourceMappingURL=trusted-project-context.js.map

package/dist/config/trusted-project-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-project-context.js","sourceRoot":"","sources":["../../src/config/trusted-project-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAA;AAE1E;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAmC,CAAA;AAEvE,MAAM,UAAU,yBAAyB,CACxC,SAAY,EACZ,OAA2B;IAE3B,gBAAgB,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IACxC,OAAO,SAAS,CAAA;AACjB,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAmB,SAAY,EAAE,GAAW;IACvF,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IAC/C,OAAO,OAAO,CAAC,CAAC,CAAE,OAAO,CAAC,GAAG,CAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,GAAW;IACnE,OAAO,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;AACzE,CAAC"}

package/dist/context/project-path.d.ts

@@ -0,0 +1,3 @@
+/** Render an instruction path without terminal controls or visual reordering. */
+export declare function visibleProjectInstructionPath(path: string): string;
+//# sourceMappingURL=project-path.d.ts.map

package/dist/context/project-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-path.d.ts","sourceRoot":"","sources":["../../src/context/project-path.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAclE"}

package/dist/context/project-path.js

@@ -0,0 +1,16 @@
+/** Render an instruction path without terminal controls or visual reordering. */
+export function visibleProjectInstructionPath(path) {
+    return [...path]
+        .map((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        const unsafe = code <= 0x1f ||
+            (code >= 0x7f && code <= 0x9f) ||
+            code === 0x2028 ||
+            code === 0x2029 ||
+            (code >= 0x202a && code <= 0x202e) ||
+            (code >= 0x2066 && code <= 0x2069);
+        return unsafe ? `\\u${code.toString(16).padStart(4, '0')}` : character;
+    })
+        .join('');
+}
+//# sourceMappingURL=project-path.js.map

package/dist/context/project-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-path.js","sourceRoot":"","sources":["../../src/context/project-path.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,UAAU,6BAA6B,CAAC,IAAY;IACzD,OAAO,CAAC,GAAG,IAAI,CAAC;SACd,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QAClB,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAC1C,MAAM,MAAM,GACX,IAAI,IAAI,IAAI;YACZ,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC;YAC9B,IAAI,KAAK,MAAM;YACf,IAAI,KAAK,MAAM;YACf,CAAC,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC;YAClC,CAAC,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,CAAA;QACnC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IACvE,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAA;AACX,CAAC"}

package/dist/context/project-tracker.d.ts

@@ -0,0 +1,30 @@
+import { type Message, type ProjectInstructionContext, type UserMessage } from '@namzu/sdk';
+import { type SkippedInstructionFile } from './project.js';
+/** Total model-visible instruction text held by one session. */
+export declare const MAX_TOTAL_PROJECT_INSTRUCTION_CHARS = 256000;
+/**
+ * Session-owned live instruction state. Each run gets its own drain cursor;
+ * children share discovery without being able to consume the parent's update.
+ */
+export declare class ProjectInstructionTracker {
+    private readonly cwd;
+    private readonly root;
+    private readonly scopes;
+    constructor(cwd: string);
+    /** Re-read only paths named by validated provenance; persisted text is ignored. */
+    rehydrate(messages: readonly Message[]): void;
+    /** Refresh known scopes and return the exact policy for a new human turn. */
+    prepareSnapshot(messages: readonly Message[]): UserMessage | null;
+    /** Each run's durable messages are its cursor over the shared discovered state. */
+    createRunContext(): ProjectInstructionContext;
+    get instructionFiles(): readonly string[];
+    get skippedInstructionFiles(): readonly SkippedInstructionFile[];
+    private observe;
+    private registerPath;
+    private refreshDirectories;
+    private view;
+    private snapshot;
+    private snapshotKey;
+    private snapshotKeyFromMessages;
+}
+//# sourceMappingURL=project-tracker.d.ts.map

package/dist/context/project-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-tracker.d.ts","sourceRoot":"","sources":["../../src/context/project-tracker.ts"],"names":[],"mappings":"AAEA,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,yBAAyB,EAE9B,KAAK,WAAW,EAGhB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAIN,KAAK,sBAAsB,EAG3B,MAAM,cAAc,CAAA;AAErB,gEAAgE;AAChE,eAAO,MAAM,mCAAmC,SAAU,CAAA;AA0D1D;;;GAGG;AACH,qBAAa,yBAAyB;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAE3C,GAAG,EAAE,MAAM;IAMvB,mFAAmF;IACnF,SAAS,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAa7C,6EAA6E;IAC7E,eAAe,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,WAAW,GAAG,IAAI;IAKjE,mFAAmF;IACnF,gBAAgB,IAAI,yBAAyB;IAa7C,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAExC;IAED,IAAI,uBAAuB,IAAI,SAAS,sBAAsB,EAAE,CAE/D;IAED,OAAO,CAAC,OAAO;IAyBf,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,IAAI;IAkDZ,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,uBAAuB;CAa/B"}

package/dist/context/project-tracker.js

@@ -0,0 +1,217 @@
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { MAX_PROJECT_INSTRUCTION_SOURCE_FILES, createProjectInstructionMessage, isProjectInstructionMessageSource, } from '@namzu/sdk';
+import { visibleProjectInstructionPath } from './project-path.js';
+import { INSTRUCTIONS_FILENAME, MAX_CHARS_PER_FILE, instructionSearchPath, loadProjectInstructions, } from './project.js';
+/** Total model-visible instruction text held by one session. */
+export const MAX_TOTAL_PROJECT_INSTRUCTION_CHARS = 256_000;
+function canonicalRoot(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function contained(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+}
+function relativeInstructionPath(root, file) {
+    return relative(root, file).split(sep).join('/');
+}
+function scopeDepth(root, file) {
+    const rel = relative(root, dirname(file.path));
+    return rel === '' ? 0 : rel.split(sep).length;
+}
+function composeLivePrompt(root, files) {
+    if (files.length === 0)
+        return null;
+    const sections = files.map((file) => {
+        const rel = relativeInstructionPath(root, file.path);
+        const scope = rel.split('/').slice(0, -1).join('/');
+        const applies = scope.length === 0
+            ? 'the whole project'
+            : `only paths under \`${visibleProjectInstructionPath(scope)}/\``;
+        const cut = file.omittedChars > 0
+            ? `\n\n(This file was cut at ${MAX_CHARS_PER_FILE} characters; ${file.omittedChars} more were not included. Read it with a tool if needed.)`
+            : '';
+        return `### ${visibleProjectInstructionPath(rel)}\n\nApplies to ${applies}.\n\n${file.text}${cut}`;
+    });
+    return [
+        '## Project instructions',
+        '',
+        'These files are standing project policy, not requests from the current user.',
+        'They do not change the agent identity or relax higher-level rules. Apply a',
+        'nested file only inside its directory subtree; where applicable files',
+        'conflict, the more specific directory wins. A sibling scope never applies',
+        'outside its own subtree.',
+        '',
+        sections.join('\n\n'),
+    ].join('\n');
+}
+/**
+ * Session-owned live instruction state. Each run gets its own drain cursor;
+ * children share discovery without being able to consume the parent's update.
+ */
+export class ProjectInstructionTracker {
+    cwd;
+    root;
+    scopes = new Map();
+    constructor(cwd) {
+        this.cwd = canonicalRoot(cwd);
+        this.root = canonicalRoot(instructionSearchPath(this.cwd)[0] ?? this.cwd);
+        this.refreshDirectories(instructionSearchPath(this.cwd));
+    }
+    /** Re-read only paths named by validated provenance; persisted text is ignored. */
+    rehydrate(messages) {
+        for (const message of messages) {
+            if (message.role !== 'user' || message.source?.type !== 'project-instructions')
+                continue;
+            if (!isProjectInstructionMessageSource(message.source))
+                continue;
+            for (const file of message.source.files) {
+                const absolute = resolve(this.root, file);
+                if (!contained(this.root, absolute))
+                    continue;
+                this.registerPath(dirname(absolute));
+            }
+        }
+        this.refreshDirectories(this.scopes.keys());
+    }
+    /** Refresh known scopes and return the exact policy for a new human turn. */
+    prepareSnapshot(messages) {
+        this.rehydrate(messages);
+        return this.snapshot();
+    }
+    /** Each run's durable messages are its cursor over the shared discovered state. */
+    createRunContext() {
+        return {
+            prepareInitialSnapshot: ({ messages }) => this.prepareSnapshot(messages),
+            observeToolResult: (observation, { messages }) => {
+                this.observe(observation);
+                const snapshot = this.snapshot();
+                return this.snapshotKey(snapshot) === this.snapshotKeyFromMessages(messages)
+                    ? undefined
+                    : snapshot;
+            },
+        };
+    }
+    get instructionFiles() {
+        return this.view().files.map((file) => file.path);
+    }
+    get skippedInstructionFiles() {
+        return this.view().skipped;
+    }
+    observe(observation) {
+        if (!observation.result.success || !['read', 'write', 'edit'].includes(observation.toolName)) {
+            return;
+        }
+        if (typeof observation.input !== 'object' ||
+            observation.input === null ||
+            !('path' in observation.input) ||
+            typeof observation.input.path !== 'string') {
+            return;
+        }
+        const rawPath = observation.input.path;
+        const lexical = resolve(this.cwd, rawPath);
+        let target;
+        try {
+            target = realpathSync(lexical);
+        }
+        catch {
+            return;
+        }
+        if (!contained(this.root, target))
+            return;
+        this.registerPath(dirname(target));
+        this.refreshDirectories(this.scopes.keys());
+    }
+    registerPath(directory) {
+        const target = resolve(directory);
+        if (!contained(this.root, target))
+            return;
+        const rel = relative(this.root, target);
+        let current = this.root;
+        if (!this.scopes.has(current))
+            this.scopes.set(current, { directory: current });
+        if (rel === '')
+            return;
+        for (const part of rel.split(sep)) {
+            current = join(current, part);
+            if (!this.scopes.has(current))
+                this.scopes.set(current, { directory: current });
+        }
+    }
+    refreshDirectories(directories) {
+        for (const directory of [...directories]) {
+            this.registerPath(directory);
+            const loaded = loadProjectInstructions(directory);
+            const expected = join(directory, INSTRUCTIONS_FILENAME);
+            const file = loaded.files.find((candidate) => candidate.path === expected);
+            const skipped = loaded.skipped.find((candidate) => candidate.path === expected);
+            this.scopes.set(directory, {
+                directory,
+                ...(file ? { file } : {}),
+                ...(skipped ? { skipped } : {}),
+            });
+        }
+    }
+    view() {
+        const loaded = [...this.scopes.values()].flatMap((scope) => (scope.file ? [scope.file] : []));
+        const rootFile = loaded.find((file) => dirname(file.path) === this.root);
+        const candidates = loaded
+            .filter((file) => file !== rootFile)
+            .sort((a, b) => scopeDepth(this.root, b) - scopeDepth(this.root, a) || a.path.localeCompare(b.path));
+        const selected = [];
+        let used = 0;
+        const skipped = [...this.scopes.values()].flatMap((scope) => scope.skipped ? [scope.skipped] : []);
+        for (const file of rootFile ? [rootFile, ...candidates] : candidates) {
+            const sourcePath = relativeInstructionPath(this.root, file.path);
+            if (!isProjectInstructionMessageSource({ type: 'project-instructions', files: [sourcePath] })) {
+                skipped.push({
+                    path: file.path,
+                    reason: 'its project-relative provenance is not a canonical bounded AGENTS.md path',
+                });
+                continue;
+            }
+            if (selected.length >= MAX_PROJECT_INSTRUCTION_SOURCE_FILES ||
+                used + file.text.length > MAX_TOTAL_PROJECT_INSTRUCTION_CHARS) {
+                skipped.push({
+                    path: file.path,
+                    reason: `the live project-instruction snapshot is limited to ${MAX_TOTAL_PROJECT_INSTRUCTION_CHARS} characters and ${MAX_PROJECT_INSTRUCTION_SOURCE_FILES} files`,
+                });
+                continue;
+            }
+            selected.push(file);
+            used += file.text.length;
+        }
+        selected.sort((a, b) => scopeDepth(this.root, a) - scopeDepth(this.root, b) || a.path.localeCompare(b.path));
+        return {
+            files: selected,
+            skipped: skipped.sort((a, b) => a.path.localeCompare(b.path)),
+        };
+    }
+    snapshot() {
+        const { files } = this.view();
+        const prompt = composeLivePrompt(this.root, files);
+        return prompt
+            ? createProjectInstructionMessage(prompt, files.map((file) => relativeInstructionPath(this.root, file.path)))
+            : null;
+    }
+    snapshotKey(snapshot) {
+        return snapshot ? JSON.stringify([snapshot.source, snapshot.content]) : 'null';
+    }
+    snapshotKeyFromMessages(messages) {
+        for (let index = messages.length - 1; index >= 0; index -= 1) {
+            const message = messages[index];
+            if (message?.role === 'user' &&
+                message.source?.type === 'project-instructions' &&
+                isProjectInstructionMessageSource(message.source)) {
+                return this.snapshotKey(message);
+            }
+        }
+        return 'null';
+    }
+}
+//# sourceMappingURL=project-tracker.js.map

package/dist/context/project-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-tracker.js","sourceRoot":"","sources":["../../src/context/project-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAC7E,OAAO,EACN,oCAAoC,EAKpC,+BAA+B,EAC/B,iCAAiC,GACjC,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAA;AAEjE,OAAO,EACN,qBAAqB,EACrB,kBAAkB,EAGlB,qBAAqB,EACrB,uBAAuB,GACvB,MAAM,cAAc,CAAA;AAErB,gEAAgE;AAChE,MAAM,CAAC,MAAM,mCAAmC,GAAG,OAAO,CAAA;AAQ1D,SAAS,aAAa,CAAC,IAAY;IAClC,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;AACF,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,SAAiB;IACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IACrC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAA;AACvF,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAY,EAAE,IAAY;IAC1D,OAAO,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,IAA4B;IAC7D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC9C,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAA;AAC9C,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAwC;IAChF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnC,MAAM,GAAG,GAAG,uBAAuB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;QACpD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACnD,MAAM,OAAO,GACZ,KAAK,CAAC,MAAM,KAAK,CAAC;YACjB,CAAC,CAAC,mBAAmB;YACrB,CAAC,CAAC,sBAAsB,6BAA6B,CAAC,KAAK,CAAC,KAAK,CAAA;QACnE,MAAM,GAAG,GACR,IAAI,CAAC,YAAY,GAAG,CAAC;YACpB,CAAC,CAAC,6BAA6B,kBAAkB,gBAAgB,IAAI,CAAC,YAAY,0DAA0D;YAC5I,CAAC,CAAC,EAAE,CAAA;QACN,OAAO,OAAO,6BAA6B,CAAC,GAAG,CAAC,kBAAkB,OAAO,QAAQ,IAAI,CAAC,IAAI,GAAG,GAAG,EAAE,CAAA;IACnG,CAAC,CAAC,CAAA;IACF,OAAO;QACN,yBAAyB;QACzB,EAAE;QACF,8EAA8E;QAC9E,4EAA4E;QAC5E,uEAAuE;QACvE,2EAA2E;QAC3E,0BAA0B;QAC1B,EAAE;QACF,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;KACrB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,yBAAyB;IACpB,GAAG,CAAQ;IACX,IAAI,CAAQ;IACZ,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAA;IAEvD,YAAY,GAAW;QACtB,IAAI,CAAC,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAA;QACzE,IAAI,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IACzD,CAAC;IAED,mFAAmF;IACnF,SAAS,CAAC,QAA4B;QACrC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,IAAI,KAAK,sBAAsB;gBAAE,SAAQ;YACxF,IAAI,CAAC,iCAAiC,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,SAAQ;YAChE,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;gBACzC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC;oBAAE,SAAQ;gBAC7C,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;YACrC,CAAC;QACF,CAAC;QACD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;IAED,6EAA6E;IAC7E,eAAe,CAAC,QAA4B;QAC3C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QACxB,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAA;IACvB,CAAC;IAED,mFAAmF;IACnF,gBAAgB;QACf,OAAO;YACN,sBAAsB,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC;YACxE,iBAAiB,EAAE,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;gBAChD,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;gBACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;gBAChC,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC;oBAC3E,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,QAAQ,CAAA;YACZ,CAAC;SACD,CAAA;IACF,CAAC;IAED,IAAI,gBAAgB;QACnB,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClD,CAAC;IAED,IAAI,uBAAuB;QAC1B,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAA;IAC3B,CAAC;IAEO,OAAO,CAAC,WAAkC;QACjD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9F,OAAM;QACP,CAAC;QACD,IACC,OAAO,WAAW,CAAC,KAAK,KAAK,QAAQ;YACrC,WAAW,CAAC,KAAK,KAAK,IAAI;YAC1B,CAAC,CAAC,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC;YAC9B,OAAQ,WAAW,CAAC,KAAqC,CAAC,IAAI,KAAK,QAAQ,EAC1E,CAAC;YACF,OAAM;QACP,CAAC;QACD,MAAM,OAAO,GAAI,WAAW,CAAC,KAAmC,CAAC,IAAI,CAAA;QACrE,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAC1C,IAAI,MAAc,CAAA;QAClB,IAAI,CAAC;YACJ,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;QAC/B,CAAC;QAAC,MAAM,CAAC;YACR,OAAM;QACP,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;YAAE,OAAM;QACzC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;QAClC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;IAEO,YAAY,CAAC,SAAiB;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;QACjC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;YAAE,OAAM;QACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACvC,IAAI,OAAO,GAAG,IAAI,CAAC,IAAI,CAAA;QACvB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAA;QAC/E,IAAI,GAAG,KAAK,EAAE;YAAE,OAAM;QACtB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAC7B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAA;QAChF,CAAC;IACF,CAAC;IAEO,kBAAkB,CAAC,WAA6B;QACvD,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;YAC5B,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAA;YACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAA;YACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAA;YAC1E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAA;YAC/E,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE;gBAC1B,SAAS;gBACT,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/B,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IAEO,IAAI;QAIX,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QAC7F,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,CAAA;QACxE,MAAM,UAAU,GAAG,MAAM;aACvB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC;aACnC,IAAI,CACJ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACR,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CACpF,CAAA;QACF,MAAM,QAAQ,GAA6B,EAAE,CAAA;QAC7C,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAC3D,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CACpC,CAAA;QACD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;YACtE,MAAM,UAAU,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;YAChE,IACC,CAAC,iCAAiC,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,EACxF,CAAC;gBACF,OAAO,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,MAAM,EAAE,2EAA2E;iBACnF,CAAC,CAAA;gBACF,SAAQ;YACT,CAAC;YACD,IACC,QAAQ,CAAC,MAAM,IAAI,oCAAoC;gBACvD,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,mCAAmC,EAC5D,CAAC;gBACF,OAAO,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,MAAM,EAAE,uDAAuD,mCAAmC,mBAAmB,oCAAoC,QAAQ;iBACjK,CAAC,CAAA;gBACF,SAAQ;YACT,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACnB,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAA;QACzB,CAAC;QACD,QAAQ,CAAC,IAAI,CACZ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAC7F,CAAA;QACD,OAAO;YACN,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC7D,CAAA;IACF,CAAC;IAEO,QAAQ;QACf,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QAC7B,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAClD,OAAO,MAAM;YACZ,CAAC,CAAC,+BAA+B,CAC/B,MAAM,EACN,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAClE;YACF,CAAC,CAAC,IAAI,CAAA;IACR,CAAC;IAEO,WAAW,CAAC,QAA4B;QAC/C,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAC/E,CAAC;IAEO,uBAAuB,CAAC,QAA4B;QAC3D,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;YAC/B,IACC,OAAO,EAAE,IAAI,KAAK,MAAM;gBACxB,OAAO,CAAC,MAAM,EAAE,IAAI,KAAK,sBAAsB;gBAC/C,iCAAiC,CAAC,OAAO,CAAC,MAAM,CAAC,EAChD,CAAC;gBACF,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;YACjC,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAA;IACd,CAAC;CACD"}

package/dist/context/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { type Logger, type SandboxProvider } from '@namzu/sdk';
+import { type Logger, type SandboxEnvironment, type SandboxIsolationControl, type SandboxProvider } from '@namzu/sdk';
 import type { SandboxConfig } from '../config/schema.js';
 /**
  * The sandbox a CLI run executes its commands in.
@@ -13,19 +13,39 @@ import type { SandboxConfig } from '../config/schema.js';
  * On by default now. What it enforces is a property of the machine, and
  * this module's other job is to make sure nobody has to guess which.
  */
-export interface ResolvedSandbox {
-    /** Absent when the operator turned it off. */
-    readonly provider?: SandboxProvider;
-    /** One line for the operator, always — including when it is off. */
-    readonly notice: string;
+/**
+ * What a reader needs to know about the sandbox, without the live provider.
+ *
+ * Split out so `/status` can be handed the facts rather than the object: the
+ * provider is a running thing with a filesystem under it, and a render
+ * function has no business holding one.
+ */
+export interface SandboxSummary {
     /**
      * True when commands run on the host with no confinement.
      *
-     * Either because the sandbox is off, or because this platform's
-     * environment enforces nothing. A caller that wants to warn louder in
-     * that case does not have to re-derive it from the notice text.
+     * Either because the sandbox is off, or because this platform's environment
+     * enforces nothing. A caller that wants to warn louder in that case does not
+     * have to re-derive it from the notice text.
      */
     readonly unconfined: boolean;
+    /** Absent when the operator turned the sandbox off. */
+    readonly environment?: SandboxEnvironment;
+    /** Controls this machine actually applies to a spawned command. */
+    readonly enforced: readonly SandboxIsolationControl[];
+    /**
+     * Controls the operator DEMANDED, which is not recoverable from the line
+     * above: a host that supplies `filesystem` anyway looks identical to one
+     * where it was insisted on, and only the second is a guarantee that
+     * survives moving machines.
+     */
+    readonly required: readonly SandboxIsolationControl[];
+}
+export interface ResolvedSandbox extends SandboxSummary {
+    /** Absent when the operator turned it off. */
+    readonly provider?: SandboxProvider;
+    /** One line for the operator, always — including when it is off. */
+    readonly notice: string;
 }
 /**
  * Build the sandbox for a run, or explain why there is none.

package/dist/context/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/context/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,MAAM,EAGX,KAAK,eAAe,EAEpB,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAA;IACnC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,eAAe,CAuC9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAEjF"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/context/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,MAAM,EAEX,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EAEpB,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACrD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;CACrD;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACtD,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAA;IACnC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,eAAe,CA+C9F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAEjF"}

package/dist/context/sandbox.js

@@ -14,6 +14,8 @@ export function resolveSandbox(log, config) {
         return {
             notice: "Sandbox off by configuration: commands run in this process, with this shell's environment. Remove `sandbox.enabled: false` to turn it back on.",
             unconfined: true,
+            enforced: [],
+            required: (config?.requireIsolation ?? []),
         };
     }
     const required = (config?.requireIsolation ?? []);
@@ -33,6 +35,9 @@ export function resolveSandbox(log, config) {
             provider,
             notice: `Sandbox on (${provider.environment}), but this platform enforces none of ${SANDBOX_ISOLATION_CONTROLS.join(', ')} — commands are not confined. Name what you need under \`sandbox.requireIsolation\` to be refused instead of surprised.`,
             unconfined: true,
+            environment: provider.environment,
+            enforced: [],
+            required,
         };
     }
     return {
@@ -41,6 +46,9 @@ export function resolveSandbox(log, config) {
             ? `Sandbox on (${provider.environment}): enforcing ${enforced.join(', ')}.`
             : `Sandbox on (${provider.environment}): enforcing ${enforced.join(', ')}; NOT enforcing ${missing.join(', ')}.`,
         unconfined: false,
+        environment: provider.environment,
+        enforced,
+        required,
     };
 }
 /**

package/dist/context/sandbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/context/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EAEpB,0BAA0B,EAG1B,WAAW,GACX,MAAM,YAAY,CAAA;AAiCnB;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,MAAiC;IAC5E,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;QAC/B,OAAO;YACN,MAAM,EACL,gJAAgJ;YACjJ,UAAU,EAAE,IAAI;SAChB,CAAA;IACF,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,gBAAgB,IAAI,EAAE,CAAuC,CAAA;IACvF,qEAAqE;IACrE,wEAAwE;IACxE,kEAAkE;IAClE,sCAAsC;IACtC,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,GAAG,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC,CAAA;IAE9E,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IAChD,MAAM,QAAQ,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IACpE,MAAM,OAAO,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAEpE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,8DAA8D;QAC9D,qEAAqE;QACrE,iDAAiD;QACjD,OAAO;YACN,QAAQ;YACR,MAAM,EAAE,eAAe,QAAQ,CAAC,WAAW,yCAAyC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,yHAAyH;YAClP,UAAU,EAAE,IAAI;SAChB,CAAA;IACF,CAAC;IAED,OAAO;QACN,QAAQ;QACR,MAAM,EACL,OAAO,CAAC,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,eAAe,QAAQ,CAAC,WAAW,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC3E,CAAC,CAAC,eAAe,QAAQ,CAAC,WAAW,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAClH,UAAU,EAAE,KAAK;KACjB,CAAA;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAwB;IAC/D,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;AAC5C,CAAC"}
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/context/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EAEpB,0BAA0B,EAI1B,WAAW,GACX,MAAM,YAAY,CAAA;AAsDnB;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,MAAiC;IAC5E,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;QAC/B,OAAO;YACN,MAAM,EACL,gJAAgJ;YACjJ,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,IAAI,EAAE,CAAuC;SAChF,CAAA;IACF,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,gBAAgB,IAAI,EAAE,CAAuC,CAAA;IACvF,qEAAqE;IACrE,wEAAwE;IACxE,kEAAkE;IAClE,sCAAsC;IACtC,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,GAAG,EAAE,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC,CAAA;IAE9E,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IAChD,MAAM,QAAQ,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IACpE,MAAM,OAAO,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAEpE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,8DAA8D;QAC9D,qEAAqE;QACrE,iDAAiD;QACjD,OAAO;YACN,QAAQ;YACR,MAAM,EAAE,eAAe,QAAQ,CAAC,WAAW,yCAAyC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,yHAAyH;YAClP,UAAU,EAAE,IAAI;YAChB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,QAAQ,EAAE,EAAE;YACZ,QAAQ;SACR,CAAA;IACF,CAAC;IAED,OAAO;QACN,QAAQ;QACR,MAAM,EACL,OAAO,CAAC,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,eAAe,QAAQ,CAAC,WAAW,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC3E,CAAC,CAAC,eAAe,QAAQ,CAAC,WAAW,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAClH,UAAU,EAAE,KAAK;QACjB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,QAAQ;QACR,QAAQ;KACR,CAAA;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAwB;IAC/D,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;AAC5C,CAAC"}

package/dist/exit-codes.d.ts

@@ -37,10 +37,11 @@
  *                             nothing else is. A caller who cannot tell them
  *                             apart matches on the message string, and then
  *                             the message can never be reworded.
- *   78  EXIT_BAD_CONFIG     — sysexits EX_CONFIG; a config file is present and
- *                             its contents could not be established, so the
- *                             run refused to start rather than continue with
- *                             settings it failed to read. Distinct from 2 for
+ *   78  EXIT_BAD_CONFIG     — sysexits EX_CONFIG; a config source is present
+ *                             and cannot be read or contains a known setting
+ *                             with an invalid value, so the run refuses rather
+ *                             than silently substituting another setting.
+ *                             Distinct from 2 for
  *                             the reason 2 is distinct from 0: "namzu is not
  *                             configured here" and "your configuration is
  *                             unreadable" are fixed by opposite actions, and a