@ai-outfitter/outfitter 1.5.0 → 1.7.0

package/dist/sources/SourceCache.js

@@ -1,7 +1,13 @@
 // Encodes remote `.agents` source cache paths and normalizes remote source references.
-import { isAbsolute, join, relative, resolve } from 'node:path';
+import { isAbsolute, join, posix, relative, resolve } from 'node:path';
 /** Distinguishes remote (`uri`/`github`) sources from local `path` sources. */
 export const isRemoteSource = (source) => source.uri !== undefined || source.github !== undefined;
+const fullCommitPattern = /^[a-f0-9]{40}$/u;
+const versionTagPattern = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+/** True for a ref that names one immutable revision: a full commit SHA or a version tag. */
+export const isImmutableRef = (ref) => fullCommitPattern.test(ref) || versionTagPattern.test(ref);
+/** True for an immutable ref that must be resolved to a commit via `rev-parse` (a version tag). */
+export const isVersionTagRef = (ref) => versionTagPattern.test(ref);
 export const normalizeGitUri = (uri) => (uri.startsWith('git+') ? uri.slice('git+'.length) : uri);
 export const normalizeRemoteSourceUri = (source) => {
     if (source.uri !== undefined) {
@@ -32,9 +38,33 @@ export const redactSourceUriCredentials = (uri) => {
 export const redactEmbeddedSourceCredentials = (value) => value.replace(/((?:git\+)?[A-Za-z][A-Za-z0-9+.-]*:\/\/)[^/@\s]+@/gu, '$1REDACTED@');
 export const encodeSourceUri = (uri) => Buffer.from(redactSourceUriCredentials(uri), 'utf8').toString('base64url');
 export const encodeRemoteSource = (source) => encodeSourceUri(`${normalizeRemoteSourceUri(source)}#${source.ref ?? ''}`);
+// The payload subpath a source selects, canonicalized so identical selections share one identity:
+// an omitted path, `.`, `./`, and `foo/..` all normalize to the repository root ('').
+const canonicalSourcePath = (path) => {
+    if (path === undefined)
+        return '';
+    const normalized = posix.normalize(path).replace(/\/+$/u, '');
+    return normalized === '.' ? '' : normalized;
+};
+/**
+ * A source's graph identity for dedup, visited sets, and layer ordering. It differs from
+ * {@link encodeRemoteSource} (the *checkout cache* key) in two deliberate ways:
+ *
+ * - It includes the canonicalized `path`, because two sources into different subpaths of one repo+ref
+ *   are distinct layers — deduping them on the path-less cache key would silently drop one.
+ * - It keys on the *raw* normalized URI, credentials included, not the redacted cache key. Two entries
+ *   for the same repo with different credentials are distinct configured sources; collapsing them
+ *   (the cache key redacts credentials, so both share it) could drop a valid source for a broken one.
+ *   This value is used only in ephemeral in-memory dedup/visited sets — never persisted or logged —
+ *   so carrying credentials here is safe (the cache path and every user-facing display use the
+ *   redacted forms).
+ */
+export const encodeRemoteSourceSelection = (source) => `${normalizeRemoteSourceUri(source)}#${source.ref ?? ''} ${canonicalSourcePath(source.path)}`;
 /** Resolves the one cache root used by sync, settings, layer discovery, and setup bootstrap. */
 export const resolveRemoteRepositoryCacheRoot = (homeDirectory, cacheDirectory) => cacheDirectory ?? join(homeDirectory, '.agents', 'cache');
 export const createRemoteRepositoryCachePath = (homeDirectory, source, cacheDirectory) => join(resolveRemoteRepositoryCacheRoot(homeDirectory, cacheDirectory), 'repos', encodeRemoteSource(source));
+/** The `.agents` payload root a source selects inside its materialized repository checkout. */
+export const resolveSourcePayloadRoot = (repositoryPath, source) => source.path === undefined ? repositoryPath : resolveRemoteRepositorySubpath(repositoryPath, source.path);
 export const resolveRemoteRepositorySubpath = (repositoryPath, subpath = '') => {
     if (isAbsolute(subpath)) {
         throw new Error(`Remote repository path '${subpath}' must be relative.`);

package/dist/sources/SourceCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"SourceCache.js","sourceRoot":"","sources":["../../src/sources/SourceCache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SourceCache.js","sourceRoot":"","sources":["../../src/sources/SourceCache.ts"],"names":[],"mappings":"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"}

package/dist/sources/TransitiveSources.d.ts

@@ -0,0 +1,45 @@
+import type { SourceReference } from '../settings/Settings.js';
+import type { RemoteSourceReference } from './SourceCache.js';
+/** A `github:` catalog dependency, pinned to an immutable ref, attributed to its declaring catalog. */
+export interface DeclaredRemoteSource {
+    readonly source: {
+        readonly github: string;
+        readonly ref: string;
+    };
+    /** Display name of the declaring catalog, for warnings and provenance. */
+    readonly declaredBy: string;
+}
+export interface DeclaredSourcesResult {
+    readonly sources: readonly DeclaredRemoteSource[];
+    readonly warnings: readonly string[];
+}
+/** The settings file a catalog payload root may carry: `settings.yml`, else `.agents/settings.yml`. */
+export declare const resolveCatalogSettingsPath: (payloadRoot: string) => string | undefined;
+/**
+ * Reads the `github:` catalog dependencies a cached catalog declares (content, never policy —
+ * OFTR-004.6.2). Transitive sources are deliberately the narrowest safe subset: a `github:`
+ * shorthand pinned to an immutable ref. A `uri:` source, a local `path:` source, a `path:` subpath,
+ * or a mutable ref is skipped with a warning naming the declaring catalog (OFTR-004.6.4,
+ * OFTR-004.6.5). Restricting to `github:` means every transitive fetch during `outfitter sync`
+ * passes through the private-catalog gate and can never select an arbitrary git transport (a `uri:`
+ * could name `ext::<cmd>` or a filesystem path); forbidding `path:` means a declaration can never
+ * escape its fetched checkout. An unreadable or invalid settings file skips the catalog's
+ * declarations without failing resolution (OFTR-004.6.8). (First-party default-catalog bootstrap
+ * fetches its declared closure without that interactive gate — see OFTR-004.6.10.) Broader
+ * transports remain future work under the trust model in #212.
+ */
+export declare const readDeclaredRemoteSources: (payloadRoot: string, checkoutRoot: string, declaredBy: string) => DeclaredSourcesResult;
+export interface TransitiveExpansionInput {
+    /** The directly configured sources, which seed the visited set and the first frontier. */
+    readonly directSources: readonly SourceReference[];
+    /** Maps a remote source to its cached checkout (clone) root, or undefined when it is not cached. */
+    readonly resolveCachedCheckoutRoot: (source: RemoteSourceReference) => string | undefined;
+}
+export interface TransitiveExpansionResult {
+    /** Newly discovered remote sources, breadth-first by depth then declaration order (OFTR-004.6.3). */
+    readonly sources: readonly DeclaredRemoteSource[];
+    /** Every accepted declaration, including duplicates suppressed from the resolved source graph. */
+    readonly declarations: readonly DeclaredRemoteSource[];
+    readonly warnings: readonly string[];
+}
+export declare const expandTransitiveSources: (input: TransitiveExpansionInput) => TransitiveExpansionResult;

package/dist/sources/TransitiveSources.js

@@ -0,0 +1,179 @@
+// Expands the remote-source closure that cached catalogs declare in their own settings files.
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { createSettingsLoadPlan, loadSettingsFiles } from '../settings/SettingsLoader.js';
+import { encodeRemoteSourceSelection, formatRemoteSourceDisplay, isImmutableRef, isRemoteSource, resolveSourcePayloadRoot, } from './SourceCache.js';
+// True when a filesystem entry exists at the path, *including a dangling symlink*. `existsSync`
+// follows links and reports a dangling one as absent, which would silently drop (rather than warn
+// about, per OFTR-004.6.8) a `settings.yml` committed as a broken symlink.
+const entryExists = (path) => {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The settings file a catalog payload root may carry: `settings.yml`, else `.agents/settings.yml`. */
+export const resolveCatalogSettingsPath = (payloadRoot) => {
+    const rootSettingsPath = join(payloadRoot, 'settings.yml');
+    if (entryExists(rootSettingsPath))
+        return rootSettingsPath;
+    const nestedSettingsPath = join(payloadRoot, '.agents', 'settings.yml');
+    return entryExists(nestedSettingsPath) ? nestedSettingsPath : undefined;
+};
+/** Applies the safe-subset rules to one declared source, yielding a dependency or a skip reason. */
+const classifyDeclaredSource = (declared, declaredBy) => {
+    if (!isRemoteSource(declared)) {
+        return {
+            skip: `Catalog '${declaredBy}' declares local path source '${declared.path}'; only 'github:' shorthands are resolved transitively, so it was skipped.`,
+        };
+    }
+    if (declared.github === undefined) {
+        return {
+            skip: `Catalog '${declaredBy}' declares source '${formatRemoteSourceDisplay(declared)}' as a 'uri:'; only 'github:' shorthands are resolved transitively, so it was skipped.`,
+        };
+    }
+    if (declared.path !== undefined) {
+        return {
+            skip: `Catalog '${declaredBy}' declares source '${formatRemoteSourceDisplay(declared)}' with a 'path:' subpath; transitive 'github:' sources must resolve their whole repository, so it was skipped.`,
+        };
+    }
+    if (declared.ref === undefined || !isImmutableRef(declared.ref)) {
+        return {
+            skip: `Catalog '${declaredBy}' declares source '${formatRemoteSourceDisplay(declared)}' without an immutable ref (a full commit SHA or version tag); it was skipped.`,
+        };
+    }
+    return { source: { github: declared.github, ref: declared.ref } };
+};
+/**
+ * Loads a cached catalog's own settings file, guarding against a hostile `settings.yml` committed as
+ * a symlink to a directory or a file outside the checkout (a `readFileSync` on a directory throws
+ * `EISDIR` and would crash resolution). Returns the parsed sources list, or a skip warning.
+ */
+const loadCatalogSourceList = (payloadRoot, checkoutRoot, declaredBy) => {
+    const settingsPath = resolveCatalogSettingsPath(payloadRoot);
+    if (settingsPath === undefined)
+        return { sources: [] };
+    try {
+        if (!statSync(settingsPath).isFile())
+            throw new Error('settings.yml is not a regular file');
+        // Anchor containment to the *checkout* root (the clone Outfitter created), not the payload root:
+        // a `path:` selecting a symlinked subdirectory would make the payload root itself resolve
+        // outside the clone, so anchoring there would accept an external settings.yml as "contained".
+        const relativeToCheckout = relative(realpathSync(checkoutRoot), realpathSync(settingsPath));
+        // Precise containment: a leading `..` segment (not a filename that merely starts with `..`, such
+        // as a directory named `..catalog`) or an absolute result means the settings escaped the checkout.
+        if (relativeToCheckout === '..' || relativeToCheckout.startsWith(`..${sep}`) || isAbsolute(relativeToCheckout)) {
+            throw new Error('settings.yml resolves outside the checkout');
+        }
+        // Known-accepted TOCTOU: the checkout could be swapped between this stat/realpath check and the
+        // read below. The checkout is a pinned immutable git ref that only Outfitter writes, and racing
+        // local-filesystem writes already imply broader access, so closing this window is not warranted.
+        const loaded = loadSettingsFiles(createSettingsLoadPlan([{ scope: 'remote', path: settingsPath }]));
+        if (loaded.issues.length > 0) {
+            return {
+                warning: `Catalog '${declaredBy}' declares invalid settings at '${settingsPath}'; its sources were skipped.`,
+            };
+        }
+        return { sources: loaded.files[0].settings.sources ?? [] };
+    }
+    catch {
+        return {
+            warning: `Catalog '${declaredBy}' has an unreadable settings.yml (not a regular file inside the checkout); its sources were skipped.`,
+        };
+    }
+};
+/**
+ * Reads the `github:` catalog dependencies a cached catalog declares (content, never policy —
+ * OFTR-004.6.2). Transitive sources are deliberately the narrowest safe subset: a `github:`
+ * shorthand pinned to an immutable ref. A `uri:` source, a local `path:` source, a `path:` subpath,
+ * or a mutable ref is skipped with a warning naming the declaring catalog (OFTR-004.6.4,
+ * OFTR-004.6.5). Restricting to `github:` means every transitive fetch during `outfitter sync`
+ * passes through the private-catalog gate and can never select an arbitrary git transport (a `uri:`
+ * could name `ext::<cmd>` or a filesystem path); forbidding `path:` means a declaration can never
+ * escape its fetched checkout. An unreadable or invalid settings file skips the catalog's
+ * declarations without failing resolution (OFTR-004.6.8). (First-party default-catalog bootstrap
+ * fetches its declared closure without that interactive gate — see OFTR-004.6.10.) Broader
+ * transports remain future work under the trust model in #212.
+ */
+export const readDeclaredRemoteSources = (payloadRoot, checkoutRoot, declaredBy) => {
+    const loaded = loadCatalogSourceList(payloadRoot, checkoutRoot, declaredBy);
+    if ('warning' in loaded)
+        return { sources: [], warnings: [loaded.warning] };
+    const sources = [];
+    const warnings = [];
+    for (const declared of loaded.sources) {
+        const classified = classifyDeclaredSource(declared, declaredBy);
+        if ('skip' in classified)
+            warnings.push(classified.skip);
+        else
+            sources.push({ source: classified.source, declaredBy });
+    }
+    return { sources, warnings };
+};
+/**
+ * Walks declared sources breadth-first from the directly configured sources over the local cache.
+ * A source already visited — directly configured or declared by an earlier catalog — is never
+ * expanded again, so dependency cycles terminate (OFTR-004.6.6). An uncached source stays in the
+ * result (the caller reports it) but its own declarations are unknowable until it is synced.
+ */
+// Reads one parent's cached checkout and returns the declarations it contributes. Returns `undefined`
+// (skip this parent) when it is uncached or its `path:` is absolute/escaping — a throw here would
+// otherwise crash resolution; only a directly configured source can carry such a path.
+const declarationsFromParent = (parent, resolveCachedCheckoutRoot) => {
+    const checkoutRoot = resolveCachedCheckoutRoot(parent);
+    if (checkoutRoot === undefined)
+        return undefined;
+    let payloadRoot;
+    try {
+        payloadRoot = resolveSourcePayloadRoot(checkoutRoot, parent);
+    }
+    catch {
+        return undefined;
+    }
+    if (!existsSync(payloadRoot))
+        return undefined;
+    return readDeclaredRemoteSources(payloadRoot, checkoutRoot, formatRemoteSourceDisplay(parent));
+};
+export const expandTransitiveSources = (input) => {
+    const sources = [];
+    const declarations = [];
+    const warnings = [];
+    const visited = new Set();
+    // Seed the visited set with each direct source's path-aware identity so a directly configured
+    // subpath source does not suppress a transitive whole-repository source of the same repo+ref, and
+    // so an exact duplicate direct source is expanded only once (OFTR-004.6.6).
+    let frontier = [];
+    for (const direct of input.directSources) {
+        if (!isRemoteSource(direct))
+            continue;
+        const key = encodeRemoteSourceSelection(direct);
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        frontier.push(direct);
+    }
+    while (frontier.length > 0) {
+        const next = [];
+        for (const parent of frontier) {
+            const declared = declarationsFromParent(parent, input.resolveCachedCheckoutRoot);
+            if (declared === undefined)
+                continue;
+            warnings.push(...declared.warnings);
+            for (const entry of declared.sources) {
+                declarations.push(entry);
+                const key = encodeRemoteSourceSelection(entry.source);
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                sources.push(entry);
+                next.push(entry.source);
+            }
+        }
+        frontier = next;
+    }
+    return { sources, declarations, warnings };
+};
+//# sourceMappingURL=TransitiveSources.js.map

package/dist/sources/TransitiveSources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransitiveSources.js","sourceRoot":"","sources":["../../src/sources/TransitiveSources.ts"],"names":[],"mappings":"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"}

package/dist/system/SystemExtensionHook.d.ts

@@ -0,0 +1,34 @@
+import type { AgentLaunchPlan } from '../projection/Projection.js';
+import type { Harness } from '../settings/Settings.js';
+export interface SystemExtensionHarnessHook {
+    readonly extensions?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+}
+export interface SystemExtensionHook {
+    readonly filePath: string;
+    readonly name: string;
+    readonly harnesses: Partial<Readonly<Record<Harness, SystemExtensionHarnessHook>>>;
+}
+export interface SystemExtensionHookSource {
+    readonly directory: string;
+    readonly stamp: string;
+}
+export interface LoadedSystemExtensionHooks {
+    readonly hooks: readonly SystemExtensionHook[];
+    readonly source?: SystemExtensionHookSource;
+}
+export interface AttachedSystemExtensionHooks {
+    readonly launch: AgentLaunchPlan;
+    readonly warnings: readonly string[];
+}
+export interface SystemExtensionHookDiscoveryInput {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+export declare const resolveSystemExtensionHookSource: (input?: SystemExtensionHookDiscoveryInput) => SystemExtensionHookSource | undefined;
+export declare const readSystemExtensionHooks: (input?: SystemExtensionHookDiscoveryInput) => LoadedSystemExtensionHooks;
+/**
+ * Prepends every system Pi extension after projection, including for RPC/print launches. Hook env
+ * stays beneath the projected plan env so it cannot replace Outfitter's runtime/session paths.
+ */
+export declare const attachSystemExtensionHooks: (plan: AgentLaunchPlan, loaded?: LoadedSystemExtensionHooks) => AttachedSystemExtensionHooks;

package/dist/system/SystemExtensionHook.js

@@ -0,0 +1,190 @@
+// Reads root-owned system extension hooks for post-projection launch-plan mutation. This is a
+// launcher-scope mechanism, not a managed configuration scope: Pi never reads these files, so they
+// do not change Pi's configuration resolution order. A session can still bypass the launcher with
+// the bundled Pi binary directly or point OUTFITTER_SYSTEM_DIR at an empty directory. The honest
+// guarantee is that collection is on by default and the organization owns the file naming the
+// collector, not that a session cannot turn collection off.
+//
+// Hook documents fail closed because only an operator can create files in the normal root-owned
+// locations. A malformed file is therefore an operator error caught on a canary boot; failing open
+// would silently run the fleet without collection, which downstream verifiers must classify as
+// unattested rather than clean. Hook environment also denies Node and native dynamic-loader
+// controls: they could execute code before Pi starts and change what runs rather than what observes.
+// Symlinks are resolved to physical paths and dangling links are fatal. Ownership and mode checks
+// stay with deployment policy because supported paths include platform-specific package stores and
+// the explicit development override, which do not share one portable owner or permission model.
+import { lstatSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { validateSchema } from '../validation/SchemaValidator.js';
+import { parseYamlDocument } from '../validation/YamlDocument.js';
+const linuxSystemDirectory = '/etc/outfitter/system.d';
+const macosSystemDirectory = '/Library/Application Support/Outfitter/system.d';
+const protectedPiEnvironmentVariables = new Set(['PI_CODING_AGENT_DIR', 'PI_CODING_AGENT_SESSION_DIR']);
+const runtimeControlEnvironmentVariables = new Set([
+    'LD_AUDIT',
+    'LD_LIBRARY_PATH',
+    'LD_PRELOAD',
+    'NODE_OPTIONS',
+    'NODE_REPL_EXTERNAL_MODULE',
+    // Node reads this before startup and OpenSSL configuration can activate an
+    // arbitrary native provider, so it executes code exactly like the loaders above.
+    'OPENSSL_CONF',
+]);
+export const resolveSystemExtensionHookSource = (input = {}) => {
+    const environment = input.environment ?? process.env;
+    const override = environment.OUTFITTER_SYSTEM_DIR;
+    if (override !== undefined)
+        return { directory: override, stamp: `env-override:${override}` };
+    switch (input.platform ?? process.platform) {
+        case 'darwin':
+            return { directory: macosSystemDirectory, stamp: macosSystemDirectory };
+        case 'linux':
+            return { directory: linuxSystemDirectory, stamp: linuxSystemDirectory };
+        default:
+            return undefined;
+    }
+};
+const formatValidationIssues = (filePath, issues) => issues.map((issue) => `${filePath}#${issue.path} ${issue.message}`).join('; ');
+const resolvePhysicalPath = (path, errorMessage) => {
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        throw new Error(`${errorMessage}: ${String(error)}`, { cause: error });
+    }
+};
+const resolveExtensionPaths = (document, filePath) => {
+    const harnesses = {};
+    for (const [harness, hook] of Object.entries(document.harnesses)) {
+        if (hook.extensions === undefined) {
+            harnesses[harness] = hook;
+            continue;
+        }
+        harnesses[harness] = {
+            ...hook,
+            extensions: hook.extensions.map((extensionPath) => {
+                if (!isAbsolute(extensionPath) || lstatSync(extensionPath, { throwIfNoEntry: false }) === undefined) {
+                    throw new Error(`Invalid system extension hook '${filePath}': extension path does not exist: ${extensionPath}`);
+                }
+                return resolvePhysicalPath(extensionPath, `Invalid system extension hook '${filePath}': extension path cannot be resolved: ${extensionPath}`);
+            }),
+        };
+    }
+    return { ...document, harnesses };
+};
+const assertNoProtectedPiEnvironment = (document, filePath) => {
+    for (const hook of Object.values(document.harnesses)) {
+        for (const name of Object.keys(hook.env ?? {})) {
+            if (protectedPiEnvironmentVariables.has(name.toUpperCase())) {
+                throw new Error(`Invalid system extension hook '${filePath}': environment variable '${name}' is reserved by Outfitter.`);
+            }
+        }
+    }
+};
+const assertNoRuntimeControlEnvironment = (document, filePath) => {
+    for (const hook of Object.values(document.harnesses)) {
+        for (const name of Object.keys(hook.env ?? {})) {
+            const normalizedName = name.toUpperCase();
+            if (runtimeControlEnvironmentVariables.has(normalizedName) || normalizedName.startsWith('DYLD_')) {
+                throw new Error(`Invalid system extension hook '${filePath}': environment variable '${name}' controls process loading and is forbidden.`);
+            }
+        }
+    }
+};
+const readSystemExtensionHook = (filePath) => {
+    if (lstatSync(filePath, { throwIfNoEntry: false }) === undefined) {
+        /* v8 ignore next -- the path was returned by the immediately preceding readdirSync call. */
+        throw new Error(`System extension hook '${filePath}' disappeared while loading.`);
+    }
+    const physicalFilePath = resolvePhysicalPath(filePath, `System extension hook '${filePath}' cannot be resolved`);
+    let content;
+    try {
+        content = readFileSync(physicalFilePath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`System extension hook '${physicalFilePath}' is unreadable: ${String(error)}`, { cause: error });
+    }
+    const parsed = parseYamlDocument(content, physicalFilePath);
+    if (!parsed.ok) {
+        throw new Error(`Invalid system extension hook '${physicalFilePath}': ${parsed.issue.message}`);
+    }
+    const validation = validateSchema('system-extension-hook', parsed.document);
+    if (!validation.valid) {
+        throw new Error(`Invalid system extension hook: ${formatValidationIssues(physicalFilePath, validation.issues)}`);
+    }
+    const document = parsed.document;
+    assertNoProtectedPiEnvironment(document, physicalFilePath);
+    assertNoRuntimeControlEnvironment(document, physicalFilePath);
+    return { filePath: physicalFilePath, ...resolveExtensionPaths(document, physicalFilePath) };
+};
+const assertNoEnvironmentCollisions = (hooks) => {
+    const owners = new Map();
+    for (const hook of hooks) {
+        for (const harness of ['pi', 'claude', 'codex']) {
+            for (const name of Object.keys(hook.harnesses[harness]?.env ?? {})) {
+                const key = `${harness}:${name}`;
+                const owner = owners.get(key);
+                if (owner !== undefined) {
+                    throw new Error(`Invalid system extension hooks: environment '${name}' for '${harness}' is declared by both '${owner}' and '${hook.filePath}'.`);
+                }
+                owners.set(key, hook.filePath);
+            }
+        }
+    }
+};
+export const readSystemExtensionHooks = (input = {}) => {
+    const source = resolveSystemExtensionHookSource(input);
+    if (source === undefined)
+        return { hooks: [] };
+    const sourceEntry = lstatSync(source.directory, { throwIfNoEntry: false });
+    if (sourceEntry === undefined)
+        return { hooks: [], source };
+    const physicalDirectory = resolvePhysicalPath(source.directory, `System extension hook source '${source.directory}' cannot be resolved`);
+    const sourceStat = statSync(physicalDirectory);
+    if (!sourceStat.isDirectory()) {
+        throw new Error(`System extension hook source '${physicalDirectory}' is not a directory.`);
+    }
+    const physicalSource = {
+        directory: physicalDirectory,
+        stamp: `${source.stamp.slice(0, source.stamp.length - source.directory.length)}${physicalDirectory}`,
+    };
+    const filePaths = readdirSync(physicalDirectory)
+        .filter((name) => name.endsWith('.yml'))
+        .sort()
+        .map((name) => join(physicalDirectory, name));
+    const hooks = filePaths.map(readSystemExtensionHook);
+    assertNoEnvironmentCollisions(hooks);
+    return { hooks, source: physicalSource };
+};
+const unsupportedHarnessWarnings = (hooks) => hooks.flatMap((hook) => ['claude', 'codex']
+    .filter((harness) => hook.harnesses[harness] !== undefined)
+    .map((harness) => `warning: System extension hook '${hook.name}' configures unsupported harness '${harness}'; ignoring it.`));
+/**
+ * Prepends every system Pi extension after projection, including for RPC/print launches. Hook env
+ * stays beneath the projected plan env so it cannot replace Outfitter's runtime/session paths.
+ */
+export const attachSystemExtensionHooks = (plan, loaded = readSystemExtensionHooks()) => {
+    const warnings = unsupportedHarnessWarnings(loaded.hooks);
+    if (loaded.source === undefined)
+        return { launch: plan, warnings };
+    const piHooks = loaded.hooks.flatMap((hook) => (hook.harnesses.pi === undefined ? [] : [hook.harnesses.pi]));
+    const extensionArgs = plan.command === 'pi'
+        ? piHooks.flatMap((hook) => (hook.extensions ?? []).flatMap((path) => ['--extension', path]))
+        : [];
+    const hookEnvironment = plan.command === 'pi'
+        ? piHooks.reduce((environment, hook) => ({ ...environment, ...hook.env }), {})
+        : {};
+    return {
+        launch: {
+            ...plan,
+            args: [...extensionArgs, ...plan.args],
+            env: {
+                ...hookEnvironment,
+                OUTFITTER_SYSTEM_HOOK_SOURCE: loaded.source.stamp,
+                ...plan.env,
+            },
+        },
+        warnings,
+    };
+};
+//# sourceMappingURL=SystemExtensionHook.js.map

package/dist/system/SystemExtensionHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemExtensionHook.js","sourceRoot":"","sources":["../../src/system/SystemExtensionHook.ts"],"names":[],"mappings":"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"}

package/dist/validation/SchemaValidator.d.ts

@@ -1,4 +1,4 @@
-export type SchemaName = 'settings' | 'agent';
+export type SchemaName = 'settings' | 'agent' | 'system-extension-hook';
 export interface ValidationIssue {
     readonly path: string;
     readonly message: string;

package/dist/validation/SchemaValidator.js

@@ -4,10 +4,12 @@ import { Ajv2020 } from 'ajv/dist/2020.js';
 const readSchema = (schemaFileName) => JSON.parse(readFileSync(new URL(`../schemas/${schemaFileName}`, import.meta.url), 'utf8'));
 const settingsSchema = readSchema('settings.schema.json');
 const agentSchema = readSchema('agent.schema.json');
+const systemExtensionHookSchema = readSchema('system-extension-hook.schema.json');
 const ajv = new Ajv2020({ allErrors: true });
 const validators = {
     settings: ajv.compile(settingsSchema),
     agent: ajv.compile(agentSchema),
+    'system-extension-hook': ajv.compile(systemExtensionHookSchema),
 };
 export const createValidationResult = (issues) => ({
     valid: issues.length === 0,

package/dist/validation/SchemaValidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"SchemaValidator.js","sourceRoot":"","sources":["../../src/validation/SchemaValidator.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAc3C,MAAM,UAAU,GAAG,CAAC,cAAsB,EAAW,EAAE,CACrD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,cAAc,cAAc,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7F,MAAM,cAAc,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;AAEpD,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAE7C,MAAM,UAAU,GAAyC;IACvD,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,cAA2B,CAAC;IAClD,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,WAAwB,CAAC;CAC7C,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAkC,EAAoB,EAAE,CAAC,CAAC;IAC/F,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;IAC1B,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAsB,EAAE,QAAiB,EAAoB,EAAE;IAC5F,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,sBAAsB,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,sBAAsB,CAAE,QAAQ,CAAC,MAAiC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AACjG,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAmB,EAAE,CAAC,CAAC;IAC/D,IAAI,EAAE,KAAK,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY;IAC1D,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;CAC/B,CAAC,CAAC"}
+{"version":3,"file":"SchemaValidator.js","sourceRoot":"","sources":["../../src/validation/SchemaValidator.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAc3C,MAAM,UAAU,GAAG,CAAC,cAAsB,EAAW,EAAE,CACrD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,cAAc,cAAc,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7F,MAAM,cAAc,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACpD,MAAM,yBAAyB,GAAG,UAAU,CAAC,mCAAmC,CAAC,CAAC;AAElF,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAE7C,MAAM,UAAU,GAAyC;IACvD,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,cAA2B,CAAC;IAClD,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,WAAwB,CAAC;IAC5C,uBAAuB,EAAE,GAAG,CAAC,OAAO,CAAC,yBAAsC,CAAC;CAC7E,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAkC,EAAoB,EAAE,CAAC,CAAC;IAC/F,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;IAC1B,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAsB,EAAE,QAAiB,EAAoB,EAAE;IAC5F,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,sBAAsB,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,sBAAsB,CAAE,QAAQ,CAAC,MAAiC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AACjG,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAmB,EAAE,CAAC,CAAC;IAC/D,IAAI,EAAE,KAAK,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY;IAC1D,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;CAC/B,CAAC,CAAC"}

package/docs/architecture/state_writeback_strategy.md

@@ -26,7 +26,19 @@ The user-facing state update lifecycle is:
 ## Current behavior
 
 - Projections remain temporary and reproducible by default.
-- Outfitter does not do generic post-run copy-back or JSON/YAML merge-back.
+- Outfitter does not do generic post-run copy-back or JSON/YAML merge-back. The Pi and Claude
+  adapters have narrow credential and session bridges as exceptions because the current launch flow does not
+  connect those files to durable storage through materialized declared-state symlinks. Pi declares
+  `auth.json` and `models.json` with a `symlink` default, but currently copies them from the durable
+  agent directory into the projection before launch and back from the projection afterward. Claude
+  similarly copies `.credentials.json` from `~/.claude` into the projection and copies a changed
+  file back afterward. Claude's separate `~/.claude.json` sits outside `~/.claude`, so it cannot be
+  symlinked with the rest of the config directory; Outfitter seeds a narrow whitelist into the
+  projected file and merges only `oauthAccount` back rather than copying machine-local state
+  wholesale. Claude's `CLAUDE_CONFIG_DIR` also redirects session transcripts into the projection,
+  so Outfitter seeds only the current working directory's `projects/<slug>/` before launch and
+  atomically merges projected session files from every slug back afterward. This per-file merge
+  never deletes durable history and runs after both normal and thrown launcher exits.
 - Persistent state is represented by symlinking a projection path to the native CLI fallback path.
 - Adapters may generate a concrete runtime file for a declared state path when they need deterministic launch-time reconciliation. For example, the Pi adapter can generate a transformed `settings.json` that removes native `packages` entries already supplied by composition-controlled extensions, and then mark that declared path as `discard` for write detection during the run.
 - Every adapter-declared state path has a resolved strategy before launch: settings overrides win, otherwise the adapter `default_strategy` is used, except for adapter-generated reconciliation files that are intentionally treated as discarded runtime files.
@@ -181,7 +193,7 @@ Settings may override persistence by mapping adapter-declared paths to strategy
 
 ```yaml
 state_persistence:
-  auth.json: symlink
+  auth.json: symlink # Intended policy; Pi's current launch flow uses its explicit copy bridge.
   settings.json: symlink
   plugins/: symlink
   cache/: discard
@@ -198,7 +210,7 @@ Functional examples:
 ```yaml
 # Persist logins and settings, but make caches and sessions run-local.
 state_persistence:
-  auth.json: symlink
+  auth.json: symlink # Intended policy; Pi's current launch flow uses its explicit copy bridge.
   settings.json: symlink
   cache/: discard
   sessions/: discard