@ai-outfitter/outfitter 1.5.0 → 1.6.0

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

package/docs/documentation/README.md

@@ -2,6 +2,19 @@
 
 Outfitter lays out conventions for iterating on and sharing agent configuration — agent profiles, skills, and loadouts. The docs follow that arc: **set up** your own, **understand** the pieces, **share** them across projects and your org, **automate** them on more surfaces, then contribute back. Each page keeps to one concept and links onward when you need the next one, so nothing here has to be read up front.
 
+Onboarding an organization? Start with
+[Onboard an organization with an SDLC report](./usecases/org-onboarding-sdlc-report.md) —
+one engineer runs the maturity assessment, then creates the org `.agents`
+repository with the baseline report as its first commit.
+
+## Climb the ramp (runbooks)
+
+One runbook per rung of [the adoption ramp](../philosophy.md#the-ramp-to-an-autonomous-lifecycle). Each starts where the previous one ended and closes with the one concrete step that begins the next rung. Their success checks are the signals an SDLC assessment reports, so "done" is something you run rather than something you judge.
+
+- [Share one catalog](../runbooks/share-one-catalog.md) — one pinned catalog the organization shares, instead of per-laptop configuration. (→ delegated)
+- [Run it without your laptop](../runbooks/run-without-your-laptop.md) — an event triggers the workflow, its output lands through review, and the session is captured. (→ automated)
+- [Give the agent a residence](../runbooks/give-the-agent-a-residence.md) — a named, assignable agent with an account and somewhere to live. (→ governed)
+
 ## Start (you)
 
 - [Getting started](./getting-started.md) — install, first run, default agent.
@@ -36,7 +49,7 @@ The same composition runs on every surface; only the trigger changes.
 - [Container images](./containers.md) — run the published Debian-based image persistently, extend it with apt, or use the `-nix` variant.
 - [Recurring runs](./recurring-runs.md) — loops three ways: the local loop extension, Actions cron, cluster schedules.
 - [In-cluster agents](./in-cluster.md) — resident agents, CronJobs, and subagent Jobs via Link Operator.
-- [Hooks](./hooks.md) — harness hook wiring and the protocol gap.
+- [Hooks](./hooks.md) — harness hook wiring, launcher-scope system observers, and the protocol gap.
 - [Dump](./dump-and-bake.md) — deterministic, self-contained `.agents/` dumps.
 - [State persistence](./state.md)
 - [Adapter support matrix](./support-matrix.md)

package/docs/documentation/catalogs.md

@@ -83,6 +83,43 @@ Remote entries additionally accept:
 
 Resources from all sources resolve by slug behind local layers, following [layer precedence](./concepts.md#layer-precedence). Agent-local skills keep their owning-agent namespace through cache and source merging. Outfitter reports shadowed IDs so consumers can see which source supplies a selected resource.
 
+### Catalog dependencies (transitive sources)
+
+A catalog can depend on other catalogs by declaring `sources` in its own settings file
+(`settings.yml` at its payload root, or `.agents/settings.yml`). Outfitter resolves those
+declarations transitively: syncing and resolving a catalog also fetches and layers the catalogs it
+declares, so one pinned root pulls in its dependency closure.
+
+Transitive sources are deliberately the narrowest safe subset — a `github:` shorthand pinned to an
+immutable ref — while the [remote-catalog trust model](https://github.com/ai-outfitter/outfitter/issues/212)
+is defined. Anything else a catalog declares is skipped with a warning:
+
+- **`github:` shorthand only.** A transitive source must be a `github: owner/repo` shorthand. A
+  `uri:` source declared by a catalog is skipped, because a URI can name an arbitrary git transport
+  (for example a local path or a remote helper) that a dependency should not be able to choose on
+  your behalf. Keeping to `github:` also routes every transitive fetch that `outfitter sync`
+  performs through the same private-catalog gate as your own sources. (The one exception is the
+  first-party default catalog's own closure, fetched during setup — see the note below.)
+- **Whole repository only.** A transitive `github:` source may not carry a `path:` subpath, so a
+  declaration can never point outside the repository it fetches.
+- **Pinned only.** A transitive source must pin an immutable `ref:` — a full commit SHA, or a
+  version tag such as `v1.2.0`. A commit SHA is truly immutable; a version tag is a pin the
+  dependency's maintainer could later move, in which case the next `outfitter sync` fetches the
+  new commit and reports it as `updated`. Pin dependencies you rely on to a SHA when you need the
+  closure to never change underneath you.
+- **Content only.** A depended-on catalog contributes `.agents` payload resources. Nothing else in
+  its settings file — default agent, default harness, cache directory, `remote_settings` — takes
+  effect transitively.
+- **Lower precedence.** Every source you configure directly outranks every transitive source;
+  deeper dependencies rank below shallower ones.
+- Cycles and duplicates resolve once — the first occurrence wins and resolution terminates.
+
+A fresh `outfitter` install fetches this closure during setup, so a default profile whose skills
+live in a depended-on catalog works without a manual sync. Because the default catalog is the
+first-party catalog Outfitter ships (pinned in the CLI), its bootstrap fetches the declared closure
+directly; the interactive private-catalog prompt is a property of `outfitter sync`, which is where
+you add your own third-party sources.
+
 ## Organization control repositories
 
 An `owner/.outfitter` repository distributes organization-wide resources plus shared settings that Outfitter layers below each user's local settings:
@@ -104,7 +141,10 @@ Remote settings are cached locally and merged at lower precedence than your proj
 1. Local settings are validated. Remote settings repositories are cloned or updated first, then
    merged settings are reloaded.
 2. Remote sources (including any added by remote settings) are cloned or updated.
-3. Each synced source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
+3. Sources declared by the synced catalogs themselves (see
+   [catalog dependencies](#catalog-dependencies-transitive-sources)) are fetched next, repeating
+   until the whole dependency closure is cached.
+4. Each synced source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
 
 All repositories live under `<cache_directory>/repos/<encoded-uri-and-ref>/` (default
 `~/.agents/cache`). Pinned (`ref:`) sources stay on their selected ref until you change it; unpinned
@@ -119,6 +159,23 @@ synchronization; run sync explicitly when you want network updates.
 
 Private GitHub catalogs are an enterprise feature. When sync detects a private GitHub repository, it asks for confirmation before use and records the decision in your user settings. Review the Outfitter Enterprise license or your enterprise agreement before enabling private catalogs. Non-GitHub `uri:` sources use whatever git credentials your environment already has; credentials embedded in URIs are redacted from sync output.
 
+### How sync authenticates
+
+Outfitter does not collect, store, or validate credentials. It delegates to `git`, so a private catalog clones with whatever credentials the surrounding environment already gives `git` — which differs by where sync runs:
+
+| Where          | Credential                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your machine   | Your existing git configuration: SSH agent, credential helper, or `.netrc`.                                                                       |
+| GitHub Actions | The workflow token, configured for git — see [token-permissions.md](https://github.com/ai-outfitter/actions/blob/main/docs/token-permissions.md). |
+| A cluster pod  | Supplied by the deployment: `GIT_ASKPASS` over HTTPS, or `GIT_SSH_COMMAND` for a deploy key.                                                      |
+
+Two failure modes are worth knowing before you hit them:
+
+- **Credentials belong in the environment, not the URI.** Outfitter redacts credentials from a source URI before deriving its cache path, so a URI carrying a username produces a cache entry that later runs do not read. The source URI must be byte-identical everywhere it appears.
+- **`outfitter run` does not sync.** A runtime that has never synced has an empty cache and cannot resolve a profile from it, however good its credentials are.
+
+[The forge credential model](../architecture/forge-credential-model.md) covers which credential to use where, and why.
+
 ## Trust and review
 
 Adding a catalog source means trusting its authors with your agent runtime. A catalog's resources can shape prompts and policy (agents, `agents.md`, `system-prompt.md`), add MCP servers (`mcp.json`), and ship skills whose scripts execute on your machine.
@@ -129,6 +186,8 @@ Before adding a source, review it:
 2. Read every skill you will select, including its scripts and catalog-owned `file` references (see the [trust boundary](./skills.md#trust-boundary)).
 3. Review `mcp.json` — MCP servers are code with whatever access you grant them.
 4. Check `remote_settings` targets: a settings file can add further sources you did not review.
-5. Confirm the repository's ownership and that its maintainers are who you expect.
+5. Check the catalog's own `sources`: its pinned `github:` dependencies are fetched transitively, so
+   review each one like the catalog itself.
+6. Confirm the repository's ownership and that its maintainers are who you expect.
 
 **Pin a `ref:`** — ideally a full commit SHA — for any catalog you do not maintain yourself, and always for catalogs consumed in CI (see [Running tasks in GitHub Actions](./actions.md)). A pinned ref makes updates an explicit, reviewable action — bump the ref after reviewing the diff — instead of silently pulling whatever the catalog publishes next.

package/docs/documentation/cli.md

@@ -14,13 +14,14 @@ Resolve, compose, and launch an agent. `run` is the default command, so plain `o
 | Argument / Option     | Description                                                                      |
 | --------------------- | -------------------------------------------------------------------------------- |
 | `[agent]`             | Agent slug to run. Defaults to the settings `default_agent`.                     |
-| `--harness <harness>` | Harness to launch in: `pi` or `claude`. Defaults to `default_harness`.           |
+| `--harness <harness>` | Harness to launch in: `pi`, `claude`, or `codex`. Defaults to `default_harness`. |
 | `--strict`            | Fail instead of warning when the adapter cannot project part of the composition. |
 
 Any other arguments and unrecognized options are passed through to the launched harness:
 
 ```bash
 outfitter run engineer --harness claude
+outfitter run engineer --harness codex -- exec "review this repo"
 outfitter run persona-reviewer -- --print "summarize this repo"
 ```
 

package/docs/documentation/concepts.md

@@ -12,7 +12,7 @@ flowchart LR
   adapter --> harness[Harness]
 ```
 
-Settings tell Outfitter where `.agents` resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi or Claude Code).
+Settings tell Outfitter where `.agents` resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi, Claude Code, or Codex CLI).
 
 ## The `.agents` protocol
 
@@ -80,7 +80,7 @@ Listing, validation, running, and dumping all share one resolver. What `outfitte
 
 ## Adapters
 
-An adapter projects composed resources into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; a Claude Code adapter is supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md).
+An adapter projects composed resources into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; Claude Code and Codex CLI adapters are supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md).
 
 ## State persistence
 

package/docs/documentation/hooks.md

@@ -15,6 +15,39 @@ See the [Claude Code hooks documentation](https://code.claude.com/docs/en/hooks)
 
 Pi supports a bootstrap hook via its extension mechanism: an extension passed with `--extension` runs at session start and can register tools, providers, and runtime behavior. Outfitter's own onboarding flow uses this channel. For recurring per-event behavior, Pi extensions are the native surface.
 
+## System extension hooks
+
+An organization can make a local Pi observer load by default on every `outfitter run` by installing a system extension hook. Outfitter reads hook documents in lexical filename order from:
+
+1. `$OUTFITTER_SYSTEM_DIR/*.yml` when the variable is set (the test/development seam), or
+2. `/etc/outfitter/system.d/*.yml` on Linux, or
+3. `/Library/Application Support/Outfitter/system.d/*.yml` on macOS.
+
+Each file contributes extensions and environment additively; files do not override each other. Reusing the same environment key for the same harness in two files is an error rather than an implicit precedence rule. An absent directory is a no-op. An unreadable or malformed document, including one naming an extension path that does not exist, aborts the run whether or not `--strict` is set.
+
+```yaml
+name: pensieve
+harnesses:
+  pi:
+    extensions:
+      - /nix/store/example-pensieve/lib/pensieve/collectors/pi
+    env:
+      PENSIEVE_SINK: https://pensieve.example.com
+      PENSIEVE_INSTALL_SCOPE: launcher
+```
+
+Extension entries must be absolute paths that already exist. Outfitter resolves source-directory, hook-document, and extension symlinks to physical paths before loading them; a dangling link is fatal, and `OUTFITTER_SYSTEM_HOOK_SOURCE` records the physical source directory. Package and Git specifiers are rejected, so a launch never installs a system extension from the network. Only `name` and `harnesses` are accepted at the document root, and each harness entry can contain only `extensions` and `env`; a system hook cannot select an agent, harness, model, tool, skill, or prompt.
+
+For Pi, Outfitter prepends the configured `--extension <path>` arguments after projection on every launch, including `--mode rpc`, print, and other non-interactive launches. Hook documents cannot name the Outfitter-controlled `PI_CODING_AGENT_DIR` or `PI_CODING_AGENT_SESSION_DIR` variables. They also reject `NODE_OPTIONS`, `NODE_REPL_EXTERNAL_MODULE`, `OPENSSL_CONF`, `LD_PRELOAD`, `LD_AUDIT`, `LD_LIBRARY_PATH`, and every `DYLD_*` variable because those can change process loading before Pi starts. Other hook environment is below the launch plan's own environment but above the parent process environment at spawn. `harnesses.claude` and `harnesses.codex` documents validate but are ignored with a warning; Outfitter has no equivalent extension argument for those adapters. Their native managed configuration is the stronger policy surface.
+
+### Launcher scope, not managed scope
+
+This mechanism changes who owns the file that names an extension. It does not change Pi's configuration resolution because Pi never reads the system hook document. The accurate guarantee is **collection is on by default and the organization owns the configuration**, not that the session cannot turn collection off.
+
+The `--no-extensions` option does not disable explicitly passed `--extension` paths, so it does not bypass a system hook. A session can still execute Outfitter's bundled Pi binary directly, never going through the Outfitter launcher, or set `OUTFITTER_SYSTEM_DIR` to an empty directory. Every launch whose platform resolves a hook directory records that choice in `OUTFITTER_SYSTEM_HOOK_SOURCE`: the normal value is the resolved physical system path, while an override is stamped as `env-override:<resolved-physical-path>`. Downstream evidence can therefore distinguish the normal system source from the session-settable bypass.
+
+The normal Linux and macOS directories are root-owned. Outfitter deliberately fails closed on their operator errors: a malformed file should fail on a canary boot, while failing open could silently produce fleet sessions without collection. Those sessions must be treated as unattested rather than clean.
+
 ## Roadmap
 
 > **TODO (protocol gap):** hooks are the one behavioral surface the pinned protocol revision does not model, which means hook definitions cannot yet be expressed portably in a `.agents` tree and projected per harness. The path `agents/<agent-id>/hooks/<hook-id>/` is reserved for a future agent-local hook entity and deliberately has no resolution or projection behavior today. Outfitter may need to ship its own hooks extension that adapters translate to Claude `settings.json` hooks and Pi extensions respectively, or drive the concept into a future protocol revision. Until one of those lands, treat hooks as harness-native configuration and keep them thin: call scripts that live in the tree rather than embedding logic in hook definitions.

package/docs/documentation/in-cluster.md

@@ -11,6 +11,8 @@ The Link Operator runs Outfitter-composed agents inside a Kubernetes cluster. Th
 
 The operator never interprets a profile, reads a secret's contents, or invokes the model — it provisions and starts; the agent layer does the rest.
 
+Because the operator does not look inside a Secret, the credentials a resident agent carries are the deployment's decision. A resident agent needs two forge tokens rather than one: the notification wake path accepts only a classic token, while its repository work should carry the narrowest credential available. [Give the agent a residence](../runbooks/give-the-agent-a-residence.md) is the procedure; [the forge credential model](../architecture/forge-credential-model.md) is the reasoning.
+
 ## Execution shapes
 
 | Shape                  | Kubernetes resource | Trigger                                                                                         |

package/docs/documentation/migration.md

@@ -21,7 +21,7 @@ This page is the manual migration reference, and the bundled Outfitter skill can
 | `<project>/.outfitter/local/settings.yml` (nested dir)  | `<project>/.agents/settings.local.yml` (flat, gitignored)                                                                                                                                        |
 | `profile_sources`                                       | `sources` supplying `.agents` payloads ([catalogs](./catalogs.md))                                                                                                                               |
 | `default_profile`                                       | `default_agent` naming an agent slug                                                                                                                                                             |
-| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude`)                                                                                                                      |
+| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude\|codex`)                                                                                                               |
 | `outfitter profile list` / `create` / `lint`            | `outfitter list agents` / author files directly / `outfitter validate`                                                                                                                           |
 | `profile_export` / `generated-system-prompt.md`         | `outfitter dump` ([Dump and bake](./dump-and-bake.md))                                                                                                                                           |
 | Free-form CI prompt + profile in `ai-outfitter/actions` | An agent run with structured inputs ([Actions](./actions.md)); the task/bake surface is a [future RFC](./tasks.md)                                                                               |

package/docs/documentation/personas.md

@@ -32,7 +32,7 @@ Neither tier is a resource Outfitter resolves; both are ordinary directories of
 
 ## Three ways to consume the same file
 
-- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different flags, so a hand-written passthrough only works on the harness it was written for, and fails silently on the other. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both.
+- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different native flags. Codex has no native append flag yet, so its adapter warns that the document is dropped. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both supported identity projections.
 - **Pasted into a web agent**: upload or paste the file unchanged into claude.ai project knowledge or a ChatGPT project as stakeholder context. Same artifact, zero conversion.
 - **Ordinary reading context**: any agent doing product planning, research, or writing can read the file to know who the work is for.
 

package/docs/documentation/settings.md

@@ -22,7 +22,7 @@ In a standalone `.agents` repository the repository root is the tree, so the fil
 ```yaml
 # .agents/settings.yml
 default_agent: engineer # which agent runs by default
-default_harness: pi # which harness to launch: pi or claude
+default_harness: pi # which harness to launch: pi, claude, or codex
 
 # Where protocol resources come from, beyond this tree and ~/.agents.
 sources:

package/docs/documentation/state.md

@@ -190,6 +190,33 @@ The last form is how a resident or in-cluster agent keeps continuity across rest
 
 ## Claude Code state paths
 
+Claude credentials need a narrow adapter bridge in addition to the path-keyed state below. Claude
+reads `.credentials.json` and `.claude.json` directly from `CLAUDE_CONFIG_DIR`; the ephemeral
+projection gives `.credentials.json` no durable home, and `.claude.json`'s native location
+(`~/.claude.json`, outside `~/.claude`) does not share its config-dir-relative path. Outfitter
+seeds `.credentials.json` before launch. It seeds `oauthAccount` and `hasCompletedOnboarding` when
+those keys exist in durable state. It also seeds the current working directory's accepted-trust bit
+only when that exact trust decision already exists in durable state. Afterward it copies back the
+whole `.credentials.json` when changed and atomically merges `oauthAccount`. If the durable
+credentials also changed after seeding, Outfitter preserves that concurrent refresh and warns
+instead of copying the projected credentials back. Claude MCP OAuth tokens
+live under `mcpOAuth` in `.credentials.json`, keyed by `<serverName>|<hash>`, so server
+authorizations acquired in an Outfitter-launched Claude session persist across runs through that
+whole-file copy-back. Outfitter never copies the full machine-local `~/.claude.json` into a
+projection or merges its other projected state back. Trust accepted inside an Outfitter session is
+therefore discarded, so Claude prompts for trust on every run in a workspace that was never trusted
+natively.
+
+Claude session history has a second narrow bridge because `CLAUDE_CONFIG_DIR` also redirects
+Claude's native `projects/` tree into the temporary projection. Before launch, Outfitter derives
+Claude's project slug from the absolute working directory and copies only that slug directory from
+`~/.claude/projects/`. This keeps other projects' transcripts out of the projection while making
+`claude --continue` and `claude --resume` see earlier native or Outfitter-launched sessions. After
+the run exits or throws, Outfitter merges every new or content-changed regular session file from
+the projection's slug directories back into `~/.claude/projects/` atomically with mode `0600`.
+Durable files are never deleted. A seed or copy-back failure emits a warning and does not replace
+Claude's exit code or error.
+
 The Claude Code adapter declares these paths:
 
 ```yaml