@cleocode/cleo-os 2026.4.12 → 2026.4.16

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CleoOS launcher — the batteries-included agentic development environment.
+ *
+ * Wraps Pi's `main()` entry point with the cleo-cant-bridge pre-loaded
+ * as an extension. Pi stays upstream (ULTRAPLAN L1). This is a thin
+ * launcher that injects CleoOS extensions into Pi's CLI argument list.
+ *
+ * Usage: `cleoos [pi-args...]` — launches Pi with CANT bridge extension.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * CleoOS launcher — the batteries-included agentic development environment.
+ *
+ * Wraps Pi's `main()` entry point with the cleo-cant-bridge pre-loaded
+ * as an extension. Pi stays upstream (ULTRAPLAN L1). This is a thin
+ * launcher that injects CleoOS extensions into Pi's CLI argument list.
+ *
+ * Usage: `cleoos [pi-args...]` — launches Pi with CANT bridge extension.
+ *
+ * @packageDocumentation
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCleoOsPaths } from './xdg.js';
+/**
+ * Collect CleoOS extension paths that exist on disk.
+ *
+ * Resolves the CANT bridge extension from the XDG data directory.
+ * Only returns paths for extensions that actually exist on the filesystem.
+ *
+ * @returns Array of absolute extension file paths.
+ */
+function collectExtensionPaths() {
+    const paths = resolveCleoOsPaths();
+    const extensions = [];
+    const bridgePath = join(paths.extensions, 'cleo-cant-bridge.js');
+    if (existsSync(bridgePath)) {
+        extensions.push(bridgePath);
+    }
+    return extensions;
+}
+/**
+ * Build the argument list for Pi's `main()`, injecting CleoOS extensions.
+ *
+ * Takes the user's CLI arguments (everything after `cleoos`) and prepends
+ * `--extension <path>` flags for each discovered CleoOS extension.
+ *
+ * @param userArgs - Arguments passed to `cleoos` by the user.
+ * @param extensionPaths - Resolved extension paths to inject.
+ * @returns Combined argument array for Pi's `main()`.
+ */
+function buildArgs(userArgs, extensionPaths) {
+    const extensionFlags = extensionPaths.flatMap((p) => ['--extension', p]);
+    return [...extensionFlags, ...userArgs];
+}
+/**
+ * Entry point for the `cleoos` binary.
+ *
+ * Dynamically imports Pi's coding agent (peerDependency), resolves CleoOS
+ * extension paths, and delegates to Pi's `main()` with the bridge extension
+ * injected into the argument list.
+ *
+ * Exits with code 1 if Pi is not installed, providing install instructions.
+ */
+async function main() {
+    // Dynamically import Pi — it's a peerDependency, may not be installed
+    let piMain;
+    try {
+        const pi = await import('@mariozechner/pi-coding-agent');
+        piMain = pi.main;
+    }
+    catch {
+        console.error('CleoOS requires Pi Coding Agent to be installed.\n' +
+            'Run: npm install -g @mariozechner/pi-coding-agent\n' +
+            'Then try again: cleoos');
+        process.exit(1);
+    }
+    const extensionPaths = collectExtensionPaths();
+    const args = buildArgs(process.argv.slice(2), extensionPaths);
+    await piMain(args);
+}
+main().catch((err) => {
+    console.error('CleoOS fatal:', err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;GAOG;AACH,SAAS,qBAAqB;IAC5B,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAC;IACnC,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;IACjE,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3B,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,SAAS,CAAC,QAAkB,EAAE,cAAwB;IAC7D,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,cAAc,EAAE,GAAG,QAAQ,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,IAAI;IACjB,sEAAsE;IACtE,IAAI,MAAyC,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;QACzD,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CACX,oDAAoD;YAClD,qDAAqD;YACrD,wBAAwB,CAC3B,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,cAAc,GAAG,qBAAqB,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IAE9D,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/keystore.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CleoOS keystore — Pi API key management with XDG-compliant storage.
+ *
+ * Wraps Pi's `FileAuthStorageBackend` with a CleoOS-specific XDG path so
+ * that credentials are persisted at `~/.config/cleo/auth/auth.json` (the
+ * `auth` sub-path of the CleoOS XDG config directory) rather than Pi's
+ * default location.
+ *
+ * This ensures:
+ *   - Credentials survive `cleoos` reinstalls (XDG is outside the package).
+ *   - Multiple CleoOS installations on the same host share credentials.
+ *   - The auth file lives under the XDG Config spec (`~/.config/cleo/`).
+ *
+ * @packageDocumentation
+ */
+import { FileAuthStorageBackend } from '@mariozechner/pi-coding-agent';
+/**
+ * Resolve a `FileAuthStorageBackend` configured to use the CleoOS XDG
+ * auth directory (`~/.config/cleo/auth/auth.json`).
+ *
+ * The directory is NOT created here — that is handled by the postinstall
+ * script so that directory creation is a one-time operation.
+ *
+ * @returns A `FileAuthStorageBackend` pointed at the XDG-compliant path.
+ */
+export declare function resolveKeystore(): FileAuthStorageBackend;
+//# sourceMappingURL=keystore.d.ts.map

package/dist/keystore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.d.ts","sourceRoot":"","sources":["../src/keystore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAMvE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,sBAAsB,CAIxD"}

package/dist/keystore.js

@@ -0,0 +1,35 @@
+/**
+ * CleoOS keystore — Pi API key management with XDG-compliant storage.
+ *
+ * Wraps Pi's `FileAuthStorageBackend` with a CleoOS-specific XDG path so
+ * that credentials are persisted at `~/.config/cleo/auth/auth.json` (the
+ * `auth` sub-path of the CleoOS XDG config directory) rather than Pi's
+ * default location.
+ *
+ * This ensures:
+ *   - Credentials survive `cleoos` reinstalls (XDG is outside the package).
+ *   - Multiple CleoOS installations on the same host share credentials.
+ *   - The auth file lives under the XDG Config spec (`~/.config/cleo/`).
+ *
+ * @packageDocumentation
+ */
+import { join } from 'node:path';
+import { FileAuthStorageBackend } from '@mariozechner/pi-coding-agent';
+import { resolveCleoOsPaths } from './xdg.js';
+/** Default auth file name inside the keystore directory. */
+const AUTH_FILENAME = 'auth.json';
+/**
+ * Resolve a `FileAuthStorageBackend` configured to use the CleoOS XDG
+ * auth directory (`~/.config/cleo/auth/auth.json`).
+ *
+ * The directory is NOT created here — that is handled by the postinstall
+ * script so that directory creation is a one-time operation.
+ *
+ * @returns A `FileAuthStorageBackend` pointed at the XDG-compliant path.
+ */
+export function resolveKeystore() {
+    const paths = resolveCleoOsPaths();
+    const authFilePath = join(paths.auth, AUTH_FILENAME);
+    return new FileAuthStorageBackend(authFilePath);
+}
+//# sourceMappingURL=keystore.js.map

package/dist/keystore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.js","sourceRoot":"","sources":["../src/keystore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C,4DAA4D;AAC5D,MAAM,aAAa,GAAG,WAAW,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAC;IACnC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACrD,OAAO,IAAI,sBAAsB,CAAC,YAAY,CAAC,CAAC;AAClD,CAAC"}

package/dist/postinstall.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CleoOS postinstall — scaffolds the global XDG hub and deploys extensions.
+ *
+ * Runs automatically after `npm install -g @cleocode/cleo-os`.
+ * Creates an XDG-compliant directory structure, copies the compiled CANT
+ * bridge extension to the extensions directory, and optionally invokes
+ * `cleo skills install` for any bundled CleoOS skills.
+ *
+ * Behaviour:
+ *   - Skips silently during workspace/dev installs (non-global).
+ *   - All directory creation is idempotent (no-op if directory exists).
+ *   - All file copies are idempotent (only copies if target is missing).
+ *   - Skill install is best-effort; failures are logged but not fatal.
+ *   - Missing `@mariozechner/pi-coding-agent` is handled gracefully.
+ *
+ * This source compiles to `bin/postinstall.js` via a dedicated tsconfig
+ * (see `tsconfig.postinstall.json`). The `postinstall` script in
+ * `package.json` references the compiled output at `bin/postinstall.js`.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=postinstall.d.ts.map

package/dist/postinstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postinstall.d.ts","sourceRoot":"","sources":["../src/postinstall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/postinstall.js

@@ -0,0 +1,208 @@
+/**
+ * CleoOS postinstall — scaffolds the global XDG hub and deploys extensions.
+ *
+ * Runs automatically after `npm install -g @cleocode/cleo-os`.
+ * Creates an XDG-compliant directory structure, copies the compiled CANT
+ * bridge extension to the extensions directory, and optionally invokes
+ * `cleo skills install` for any bundled CleoOS skills.
+ *
+ * Behaviour:
+ *   - Skips silently during workspace/dev installs (non-global).
+ *   - All directory creation is idempotent (no-op if directory exists).
+ *   - All file copies are idempotent (only copies if target is missing).
+ *   - Skill install is best-effort; failures are logged but not fatal.
+ *   - Missing `@mariozechner/pi-coding-agent` is handled gracefully.
+ *
+ * This source compiles to `bin/postinstall.js` via a dedicated tsconfig
+ * (see `tsconfig.postinstall.json`). The `postinstall` script in
+ * `package.json` references the compiled output at `bin/postinstall.js`.
+ *
+ * @packageDocumentation
+ */
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// ---------------------------------------------------------------------------
+// XDG path resolution (inline copy — avoids importing from dist/ which may
+// not exist when this script runs for the first time)
+// ---------------------------------------------------------------------------
+/**
+ * Inline XDG path resolution that mirrors `src/xdg.ts`.
+ *
+ * Uses an inline copy here so the postinstall script can run before
+ * the compiled `dist/` tree is available on a fresh install.
+ *
+ * @returns Resolved CleoOS XDG directory paths.
+ */
+function resolveCleoOsPaths() {
+    const home = homedir();
+    const xdgData = process.env['XDG_DATA_HOME'] ?? join(home, '.local', 'share');
+    const xdgConfig = process.env['XDG_CONFIG_HOME'] ?? join(home, '.config');
+    const data = join(xdgData, 'cleo');
+    const config = join(xdgConfig, 'cleo');
+    return {
+        data,
+        config,
+        agentDir: data,
+        extensions: join(data, 'extensions'),
+        cant: join(data, 'cant'),
+        auth: join(config, 'auth'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Global install detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect whether this is a global npm / pnpm install.
+ *
+ * Uses four heuristics in priority order:
+ *  1. `npm_config_global=true` env var (set by npm/pnpm for global installs)
+ *  2. Package path contains `lib/node_modules/` (npm global pattern)
+ *  3. Package path starts with `npm_config_prefix` (npm prefix-based check)
+ *  4. Presence of `pnpm-workspace.yaml` two levels up (workspace = dev)
+ *
+ * @returns `true` if the install appears to be a global install.
+ */
+function isGlobalInstall() {
+    const pkgRoot = resolve(__dirname, '..');
+    // Signal 1: npm_config_global env var (set by npm during global installs)
+    if (process.env['npm_config_global'] === 'true')
+        return true;
+    // Signal 2: path contains a global node_modules (npm, pnpm, yarn)
+    if (/[/\\]lib[/\\]node_modules[/\\]/.test(pkgRoot))
+        return true;
+    // Signal 3: npm_config_prefix matches the package path
+    const prefix = process.env['npm_config_prefix'];
+    if (prefix !== undefined && pkgRoot.startsWith(prefix))
+        return true;
+    // Signal 4: inside a pnpm workspace — definitely not global
+    const workspaceMarker = join(pkgRoot, '..', '..', 'pnpm-workspace.yaml');
+    if (existsSync(workspaceMarker))
+        return false;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Directory scaffolding
+// ---------------------------------------------------------------------------
+/**
+ * Idempotently create a directory if it does not already exist.
+ *
+ * @param dir - Absolute path to the directory to create.
+ */
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        process.stdout.write(`CleoOS: created ${dir}\n`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension deployment
+// ---------------------------------------------------------------------------
+/**
+ * Copy a compiled extension to the XDG extensions directory.
+ *
+ * Only copies if the target does not already exist (idempotent). The
+ * source is the compiled `.js` file in the package's `extensions/` folder.
+ *
+ * @param extensionName - Filename without the `.js` extension.
+ * @param pkgRoot - Absolute path to the installed package root.
+ * @param extensionsDir - Absolute path to the XDG extensions directory.
+ */
+function deployExtension(extensionName, pkgRoot, extensionsDir) {
+    const src = join(pkgRoot, 'extensions', `${extensionName}.js`);
+    const dest = join(extensionsDir, `${extensionName}.js`);
+    if (!existsSync(src)) {
+        process.stdout.write(`CleoOS: skipping ${extensionName}.js (source not found at ${src})\n`);
+        return;
+    }
+    if (existsSync(dest)) {
+        // Already deployed — idempotent, skip.
+        return;
+    }
+    cpSync(src, dest, { force: false });
+    process.stdout.write(`CleoOS: deployed ${extensionName}.js to ${dest}\n`);
+}
+// ---------------------------------------------------------------------------
+// Default CANT file scaffolding
+// ---------------------------------------------------------------------------
+/**
+ * Write a default `model-routing.cant` stub to the XDG CANT directory if
+ * no `.cant` files are present. This gives the user a starting point for
+ * CANT declarations without overwriting any existing work.
+ *
+ * @param cantDir - Absolute path to the XDG CANT directory.
+ */
+function scaffoldDefaultCant(cantDir) {
+    const modelRoutingPath = join(cantDir, 'model-routing.cant');
+    if (existsSync(modelRoutingPath))
+        return;
+    const stub = [
+        '# CleoOS default model-routing.cant',
+        '# Declare agents, teams, and routing rules here.',
+        '# See: https://github.com/kryptobaseddev/cleo/blob/main/docs/cant-dsl.md',
+        '',
+    ].join('\n');
+    try {
+        writeFileSync(modelRoutingPath, stub, 'utf-8');
+        process.stdout.write(`CleoOS: created default ${modelRoutingPath}\n`);
+    }
+    catch {
+        // Best-effort: non-fatal.
+    }
+}
+// ---------------------------------------------------------------------------
+// Skill installation
+// ---------------------------------------------------------------------------
+/**
+ * Invoke `cleo skills install` via `execFileSync` to register the CleoOS
+ * bundled skills with the project. This is best-effort — if `cleo` is not
+ * on PATH or the command fails, we log and continue.
+ *
+ * Uses `execFileSync` (not `exec`) to prevent shell injection: the command
+ * and arguments are passed as separate parameters so no shell is spawned.
+ */
+function installSkills() {
+    try {
+        execFileSync('cleo', ['skills', 'install'], { stdio: 'inherit' });
+        process.stdout.write('CleoOS: skills install complete\n');
+    }
+    catch {
+        // cleo may not be installed or skills may already be up to date.
+        process.stdout.write('CleoOS: skipping skills install (cleo not found or already installed)\n');
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+/**
+ * Entry point for the CleoOS postinstall script.
+ *
+ * Orchestrates directory scaffolding, extension deployment, CANT stub
+ * creation, and optional skill installation. All operations are idempotent.
+ */
+function main() {
+    if (!isGlobalInstall()) {
+        process.stdout.write('CleoOS: skipping postinstall (not global install)\n');
+        return;
+    }
+    const paths = resolveCleoOsPaths();
+    const pkgRoot = resolve(__dirname, '..');
+    // 1. Scaffold XDG directories
+    for (const dir of [paths.data, paths.config, paths.extensions, paths.cant, paths.auth]) {
+        ensureDir(dir);
+    }
+    // 2. Deploy compiled extensions
+    deployExtension('cleo-cant-bridge', pkgRoot, paths.extensions);
+    deployExtension('cleo-chatroom', pkgRoot, paths.extensions);
+    // 3. Write default CANT stub (only if file does not exist)
+    scaffoldDefaultCant(paths.cant);
+    // 4. Install CleoOS skills (best-effort)
+    installSkills();
+    process.stdout.write('CleoOS: postinstall complete\n');
+}
+main();
+//# sourceMappingURL=postinstall.js.map

package/dist/postinstall.js.map

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

package/dist/xdg.d.ts

@@ -0,0 +1,38 @@
+/**
+ * XDG-compliant path resolution for CleoOS.
+ *
+ * Resolves:
+ * - Data: $XDG_DATA_HOME/cleo/ or ~/.local/share/cleo/
+ * - Config: $XDG_CONFIG_HOME/cleo/ or ~/.config/cleo/
+ * - Agent dir: same as data root (Pi's agentDir equivalent)
+ * - Extensions: <data>/extensions/
+ * - CANT source: <data>/cant/ (global tier)
+ *
+ * @packageDocumentation
+ */
+/** Resolved CleoOS filesystem paths following XDG Base Directory Specification. */
+export interface CleoOsPaths {
+    /** XDG data home: ~/.local/share/cleo/ */
+    data: string;
+    /** XDG config home: ~/.config/cleo/ */
+    config: string;
+    /** Pi agent directory (= data root) */
+    agentDir: string;
+    /** Extensions directory: <data>/extensions/ */
+    extensions: string;
+    /** Global CANT source: <data>/cant/ */
+    cant: string;
+    /** Auth/keystore directory: <config>/auth/ */
+    auth: string;
+}
+/**
+ * Resolve CleoOS filesystem paths using XDG Base Directory Specification.
+ *
+ * Respects `XDG_DATA_HOME` and `XDG_CONFIG_HOME` environment variables
+ * when set, falling back to the XDG defaults (`~/.local/share/` and
+ * `~/.config/` respectively).
+ *
+ * @returns Resolved paths for all CleoOS directories.
+ */
+export declare function resolveCleoOsPaths(): CleoOsPaths;
+//# sourceMappingURL=xdg.d.ts.map

package/dist/xdg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xdg.d.ts","sourceRoot":"","sources":["../src/xdg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CAgBhD"}

package/dist/xdg.js

@@ -0,0 +1,39 @@
+/**
+ * XDG-compliant path resolution for CleoOS.
+ *
+ * Resolves:
+ * - Data: $XDG_DATA_HOME/cleo/ or ~/.local/share/cleo/
+ * - Config: $XDG_CONFIG_HOME/cleo/ or ~/.config/cleo/
+ * - Agent dir: same as data root (Pi's agentDir equivalent)
+ * - Extensions: <data>/extensions/
+ * - CANT source: <data>/cant/ (global tier)
+ *
+ * @packageDocumentation
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Resolve CleoOS filesystem paths using XDG Base Directory Specification.
+ *
+ * Respects `XDG_DATA_HOME` and `XDG_CONFIG_HOME` environment variables
+ * when set, falling back to the XDG defaults (`~/.local/share/` and
+ * `~/.config/` respectively).
+ *
+ * @returns Resolved paths for all CleoOS directories.
+ */
+export function resolveCleoOsPaths() {
+    const home = homedir();
+    const xdgData = process.env['XDG_DATA_HOME'] ?? join(home, '.local', 'share');
+    const xdgConfig = process.env['XDG_CONFIG_HOME'] ?? join(home, '.config');
+    const data = join(xdgData, 'cleo');
+    const config = join(xdgConfig, 'cleo');
+    return {
+        data,
+        config,
+        agentDir: data,
+        extensions: join(data, 'extensions'),
+        cant: join(data, 'cant'),
+        auth: join(config, 'auth'),
+    };
+}
+//# sourceMappingURL=xdg.js.map

package/dist/xdg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xdg.js","sourceRoot":"","sources":["../src/xdg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAkBjC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAE1E,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAEvC,OAAO;QACL,IAAI;QACJ,MAAM;QACN,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC;QACpC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/extensions/cleo-cant-bridge.ts

@@ -0,0 +1,598 @@
+/**
+ * CleoOS CANT bridge — Wave 2 Pi extension.
+ *
+ * CANONICAL LOCATION: `packages/cleo-os/extensions/cleo-cant-bridge.ts`
+ *
+ * This file was copied from
+ * `packages/cleo/templates/cleoos-hub/pi-extensions/cleo-cant-bridge.ts`
+ * (T393). The template path is kept for reference but this file is the
+ * authoritative source. A future cleanup wave (post-T381) should remove
+ * the template copy once all consumers have migrated.
+ *
+ * Installed to: $XDG_DATA_HOME/cleo/extensions/cleo-cant-bridge.js
+ * Loaded by:    Pi via `--extension <path>` injected by CleoOS cli.ts
+ *
+ * This bridge discovers `.cant` files in the project's `.cleo/cant/`
+ * directory at session start, compiles them via `@cleocode/cant`'s
+ * `compileBundle()`, and appends the compiled declarations to Pi's
+ * system prompt on `before_agent_start`. This gives the LLM awareness
+ * of all declared agents, teams, and tools without hand-authored
+ * protocol text.
+ *
+ * Wave 2 scope:
+ *   - Scans project tier only: `<cwd>/.cleo/cant/` (recursive)
+ *   - Three-tier resolution (global, user, project) is Wave 5
+ *   - Prompt strategy: APPEND (per ULTRAPLAN L6, never replace)
+ *
+ * Wave 8 additions (T420):
+ *   - validate-on-load mental-model injection
+ *   - When the spawned agent's CANT definition has a `mentalModel` block,
+ *     fetches prior mental-model observations via memoryFind and injects
+ *     them into the Pi system prompt with VALIDATE_ON_LOAD_PREAMBLE.
+ *   - Exports `VALIDATE_ON_LOAD_PREAMBLE` and `buildMentalModelInjection`
+ *     for testability (T421).
+ *
+ * Requirements:
+ *   - `@cleocode/cant` must be installed (provides `compileBundle`)
+ *   - Pi coding agent runtime (`@mariozechner/pi-coding-agent`)
+ *
+ * Guardrails:
+ *   - Best-effort: if `@cleocode/cant` is not installed or `.cleo/cant`
+ *     does not exist, the bridge is a no-op. NEVER crash Pi.
+ *   - NO top-level await; all work happens inside event handlers.
+ *   - APPEND to system prompt, never replace.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+
+// ============================================================================
+// T420: validate-on-load constants and pure helpers
+// ============================================================================
+
+/**
+ * Preamble text injected into the Pi system prompt when an agent has a
+ * `mental_model:` CANT block. The agent MUST re-evaluate each observation
+ * against the current project state before acting.
+ *
+ * Exported so empirical tests (T421) can assert on its presence.
+ */
+export const VALIDATE_ON_LOAD_PREAMBLE =
+  "===== MENTAL MODEL (validate-on-load) =====\n" +
+  "These are your prior observations, patterns, and learnings for this project.\n" +
+  "Before acting, you MUST re-evaluate each entry against current project state.\n" +
+  "If an entry is stale, note it and proceed with fresh understanding.";
+
+/** Minimal observation shape returned by memoryFind / searchBrainCompact. */
+export interface MentalModelObservation {
+  id: string;
+  type: string;
+  title: string;
+  date?: string;
+}
+
+/**
+ * Build the validate-on-load mental-model injection string.
+ *
+ * Pure function — no I/O, safe to call in tests without a real DB.
+ *
+ * @param agentName - Name of the spawned agent (used in the header line).
+ * @param observations - Prior mental-model observations to list.
+ * @returns System-prompt block containing the preamble and numbered observations,
+ *          or an empty string when `observations` is empty.
+ */
+export function buildMentalModelInjection(
+  agentName: string,
+  observations: MentalModelObservation[],
+): string {
+  if (observations.length === 0) return "";
+
+  const lines: string[] = [
+    "",
+    `// Agent: ${agentName}`,
+    VALIDATE_ON_LOAD_PREAMBLE,
+    "",
+  ];
+
+  for (let i = 0; i < observations.length; i++) {
+    const obs = observations[i];
+    const datePart = obs.date ? ` [${obs.date}]` : "";
+    lines.push(`${i + 1}. [${obs.id}] (${obs.type})${datePart}: ${obs.title}`);
+  }
+
+  lines.push("===== END MENTAL MODEL =====");
+
+  return lines.join("\n");
+}
+
+// ============================================================================
+// T424: Path-ACL helpers (pure, no external deps)
+// ============================================================================
+
+/**
+ * Path-scoped file permissions shape expected in an agentDef at runtime.
+ *
+ * Mirrors `PathPermissions` from `@cleocode/cant` (T423).
+ * Kept inline here to avoid a direct runtime import in the Pi extension context.
+ *
+ * @task T424
+ */
+interface AgentFilePermissions {
+  /** Glob patterns the agent may write to. Empty array = no writes allowed. */
+  write?: string[];
+  /** Glob patterns the agent may read from. */
+  read?: string[];
+  /** Glob patterns the agent may delete. */
+  delete?: string[];
+}
+
+/**
+ * Convert a glob pattern to a RegExp for path matching.
+ *
+ * Supports the subset of glob syntax used in CANT file permissions:
+ * - `**` matches any path segment sequence (including none)
+ * - `*` matches any characters within a single path segment
+ * - `?` matches a single character
+ * - All other characters are treated as literals
+ *
+ * @param glob - The glob pattern string.
+ * @returns A RegExp that tests absolute or relative file paths.
+ */
+function globToRegExp(glob: string): RegExp {
+  // Escape special regex characters except our glob specials
+  let regexStr = "";
+  let i = 0;
+  while (i < glob.length) {
+    const char = glob[i];
+    if (char === "*" && glob[i + 1] === "*") {
+      // ** matches everything including path separators
+      regexStr += ".*";
+      i += 2;
+      // Skip optional trailing slash after **
+      if (glob[i] === "/") i++;
+    } else if (char === "*") {
+      // * matches anything except path separator
+      regexStr += "[^/]*";
+      i++;
+    } else if (char === "?") {
+      regexStr += "[^/]";
+      i++;
+    } else if (/[.+^${}()|[\]\\]/.test(char)) {
+      regexStr += "\\" + char;
+      i++;
+    } else {
+      regexStr += char;
+      i++;
+    }
+  }
+  return new RegExp("^" + regexStr + "$");
+}
+
+/**
+ * Test whether a file path matches any of the provided glob patterns.
+ *
+ * Normalises the path to use forward slashes. Returns `false` immediately
+ * when `globs` is an empty array (default-deny for empty write lists).
+ *
+ * @param filePath - The file path to test (absolute or relative).
+ * @param globs - The glob patterns to test against.
+ * @returns `true` if `filePath` matches at least one glob pattern.
+ */
+function matchesAnyGlob(filePath: string, globs: string[]): boolean {
+  if (globs.length === 0) return false;
+  // Normalise separators; strip leading slash for relative matching
+  const normalized = filePath.replace(/\\/g, "/").replace(/^\//, "");
+  for (const glob of globs) {
+    if (globToRegExp(glob).test(normalized)) return true;
+  }
+  return false;
+}
+
+/**
+ * Attempt to extract the target file path from a Pi tool_call event.
+ *
+ * Handles the three writable tool shapes:
+ * - `Edit`: `{ input: { file_path: string } }` or `{ filePath: string }`
+ * - `Write`: `{ input: { file_path: string } }` or `{ filePath: string }`
+ * - `Bash`: best-effort scan of the command string for write destinations
+ *
+ * Returns `null` when the path cannot be determined (allow-by-default for Bash
+ * when the destination is ambiguous).
+ *
+ * @param toolName - The tool being invoked ("Edit", "Write", or "Bash").
+ * @param toolInput - The raw tool input object.
+ * @returns The extracted file path, or `null` if not determinable.
+ */
+function extractTargetPath(
+  toolName: string,
+  toolInput: Record<string, unknown> | undefined,
+): string | null {
+  if (!toolInput) return null;
+
+  if (toolName === "Edit" || toolName === "Write") {
+    // Pi uses snake_case in the actual tool call input
+    if (typeof toolInput["file_path"] === "string") return toolInput["file_path"];
+    // camelCase fallback (bridge convention)
+    if (typeof toolInput["filePath"] === "string") return toolInput["filePath"];
+    // path fallback
+    if (typeof toolInput["path"] === "string") return toolInput["path"];
+    return null;
+  }
+
+  if (toolName === "Bash") {
+    const cmd = typeof toolInput["command"] === "string" ? toolInput["command"] : null;
+    if (!cmd) return null;
+
+    // Detect common write patterns: redirection, tee, cp/mv destination
+    // Best-effort: return the first detected destination path.
+    // If ambiguous, return null (allow-by-default for Bash).
+    const redirectMatch = cmd.match(/>\s*["']?([^\s"';&|]+)/);
+    if (redirectMatch?.[1]) return redirectMatch[1];
+
+    const teeMatch = cmd.match(/\btee\s+(?:-a\s+)?["']?([^\s"';&|]+)/);
+    if (teeMatch?.[1]) return teeMatch[1];
+
+    // cp/mv destination is the last argument — very heuristic
+    const cpMvMatch = cmd.match(/\b(?:cp|mv)\s+\S+\s+["']?([^\s"';&|]+)/);
+    if (cpMvMatch?.[1]) return cpMvMatch[1];
+
+    return null; // Cannot determine — allow (workers self-report)
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Internal state
+// ============================================================================
+
+/** Cached system prompt addendum from the last session_start compilation. */
+let bundlePrompt: string | null = null;
+
+/** Diagnostic summary cached for /cant:bundle-info. */
+let lastDiagnosticSummary: string | null = null;
+
+/**
+ * Recursively discover `.cant` files in a directory.
+ *
+ * @param dir - The directory to scan recursively.
+ * @returns An array of absolute paths to `.cant` files found.
+ */
+function discoverCantFiles(dir: string): string[] {
+  try {
+    const entries = readdirSync(dir, { recursive: true, withFileTypes: true });
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".cant")) {
+        // Node 24+ recursive readdir returns entries with parentPath
+        const parent = (entry as unknown as { parentPath?: string }).parentPath ?? dir;
+        files.push(join(parent, entry.name));
+      }
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+// ============================================================================
+// T420: mental-model injection helper (async, calls memoryFind)
+// ============================================================================
+
+/**
+ * Fetch prior mental-model observations for an agent and build the
+ * validate-on-load injection block.
+ *
+ * Called in `before_agent_start` when the agent has a `mentalModel` CANT block.
+ * Best-effort: returns empty string on any failure so Pi is never blocked.
+ *
+ * @param agentName - Name of the spawned agent.
+ * @param projectRoot - Project root directory for brain.db access.
+ * @returns The validate-on-load system-prompt block, or "" on failure/empty.
+ */
+async function fetchMentalModelInjection(
+  agentName: string,
+  projectRoot: string,
+): Promise<string> {
+  try {
+    // Lazy import: @cleocode/core may not be present in all environments.
+    // memoryFind is the engine-compat wrapper (T418) that accepts `agent`.
+    const coreModule = (await import("@cleocode/core")) as {
+      memoryFind?: (
+        params: {
+          query: string;
+          agent?: string;
+          limit?: number;
+          tables?: string[];
+        },
+        projectRoot?: string,
+      ) => Promise<{
+        success: boolean;
+        data?: {
+          results?: MentalModelObservation[];
+        };
+      }>;
+    };
+
+    if (typeof coreModule.memoryFind !== "function") return "";
+
+    // Fetch the 10 most recent mental-model observations for this agent.
+    // Use tables filter to avoid decisions/patterns/learnings which are
+    // not agent-scoped in the current schema.
+    const result = await coreModule.memoryFind(
+      {
+        query: agentName,
+        agent: agentName,
+        limit: 10,
+        tables: ["observations"],
+      },
+      projectRoot,
+    );
+
+    if (!result.success || !result.data?.results?.length) return "";
+
+    return buildMentalModelInjection(agentName, result.data.results);
+  } catch {
+    // Best-effort — never crash Pi
+    return "";
+  }
+}
+
+// ============================================================================
+// Pi extension factory
+// ============================================================================
+
+/**
+ * Pi extension factory for the CleoOS CANT bridge.
+ *
+ * Registers event handlers for `session_start` (compile `.cant` files)
+ * and `before_agent_start` (append compiled bundle + mental-model injection
+ * to system prompt). Also registers a `/cant:bundle-info` command for
+ * introspection.
+ *
+ * @param pi - The Pi extension API instance.
+ */
+export default function (pi: ExtensionAPI): void {
+  // session_start: discover and compile .cant files from the project tier
+  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    bundlePrompt = null;
+    lastDiagnosticSummary = null;
+
+    try {
+      const cantDir = join(ctx.cwd, ".cleo", "cant");
+      if (!existsSync(cantDir)) return;
+
+      const files = discoverCantFiles(cantDir);
+      if (files.length === 0) return;
+
+      // Dynamic import: @cleocode/cant may not be installed in all environments
+      const cantModule = (await import("@cleocode/cant")) as {
+        compileBundle: (paths: string[]) => Promise<{
+          renderSystemPrompt: () => string;
+          diagnostics: Array<{ severity: string; message: string; sourcePath: string }>;
+          agents: Array<{ name: string }>;
+          teams: Array<{ name: string }>;
+          tools: Array<{ name: string }>;
+          valid: boolean;
+        }>;
+      };
+
+      const bundle = await cantModule.compileBundle(files);
+      const prompt = bundle.renderSystemPrompt();
+
+      if (prompt.length > 0) {
+        bundlePrompt = prompt;
+      }
+
+      // Build diagnostic summary
+      const errorDiags = bundle.diagnostics.filter((d) => d.severity === "error");
+      const warnDiags = bundle.diagnostics.filter((d) => d.severity === "warning");
+      lastDiagnosticSummary = [
+        `Files: ${files.length}`,
+        `Agents: ${bundle.agents.length}`,
+        `Teams: ${bundle.teams.length}`,
+        `Tools: ${bundle.tools.length}`,
+        `Valid: ${bundle.valid}`,
+        `Errors: ${errorDiags.length}`,
+        `Warnings: ${warnDiags.length}`,
+      ].join(", ");
+
+      // Notify on errors
+      if (errorDiags.length > 0 && ctx.hasUI) {
+        ctx.ui.notify(
+          `CleoOS CANT bridge: ${errorDiags.length} validation error(s) in .cleo/cant/`,
+          "warning",
+        );
+      }
+
+      // Success notification
+      if (ctx.hasUI) {
+        ctx.ui.setStatus(
+          "cleo-cant-bridge",
+          `CANT: ${bundle.agents.length} agent(s), ${files.length} file(s)`,
+        );
+      }
+    } catch (err: unknown) {
+      // Best-effort: never crash Pi
+      const message = err instanceof Error ? err.message : String(err);
+      if (ctx.hasUI) {
+        ctx.ui.notify(`CleoOS CANT bridge: ${message}`, "warning");
+      }
+    }
+  });
+
+  // before_agent_start: APPEND compiled bundle prompt + mental-model injection
+  // to system prompt (per ULTRAPLAN L6, never replace)
+  pi.on(
+    "before_agent_start",
+    async (
+      event: {
+        systemPrompt?: string;
+        agentName?: string;
+        /** T420: agent CANT definition, if resolved by Pi runtime. */
+        agentDef?: {
+          /** mentalModel block presence signals validate-on-load injection. */
+          mentalModel?: unknown;
+        };
+        /** Project root injected by Pi when available. */
+        projectRoot?: string;
+      },
+      ctx?: ExtensionContext,
+    ) => {
+      const existingPrompt = event.systemPrompt ?? "";
+      let appendix = "";
+
+      // APPEND CANT bundle prompt
+      if (bundlePrompt) {
+        appendix += "\n\n" + bundlePrompt;
+      }
+
+      // T420: validate-on-load mental-model injection.
+      // Inject when the agent has a `mentalModel` CANT block.
+      const agentName = event.agentName;
+      const hasMentalModel =
+        agentName !== undefined &&
+        agentName !== "" &&
+        event.agentDef?.mentalModel !== undefined;
+
+      if (hasMentalModel && agentName) {
+        // Resolve project root: prefer explicit field, fall back to ctx.cwd
+        const projectRoot = event.projectRoot ?? ctx?.cwd ?? "";
+        if (projectRoot) {
+          const mentalModelBlock = await fetchMentalModelInjection(agentName, projectRoot);
+          if (mentalModelBlock) {
+            appendix += mentalModelBlock;
+          }
+        }
+      }
+
+      if (!appendix) return {};
+
+      return {
+        systemPrompt: existingPrompt + appendix,
+      };
+    },
+  );
+
+  // tool_call: ULTRAPLAN §10.3 — Lead agents MUST NOT execute Edit/Write/Bash.
+  // T424: Worker agents with declared file permissions are restricted to their
+  //        declared write globs. Leads dispatch; workers execute within scope.
+  // Fires on every Pi tool_call event.
+  // The before_agent_start handler (T420 validate-on-load) is NOT touched here.
+  pi.on(
+    "tool_call",
+    async (event: {
+      /** CANT agent definition resolved by Pi at spawn time, if available. */
+      agentDef?: {
+        /** Tier role declared in the .cant file (e.g. "lead", "worker", "orchestrator"). */
+        role?: string;
+        /** Path-scoped file permissions declared in the .cant file (T423). */
+        filePermissions?: AgentFilePermissions;
+        /** Agent name for diagnostic messages. */
+        name?: string;
+      };
+      /** The tool name being invoked (e.g. "Edit", "Write", "Bash"). */
+      toolName?: string;
+      /** The raw tool input object (contains file_path for Edit/Write, command for Bash). */
+      toolInput?: Record<string, unknown>;
+    }) => {
+      const agentDef = event.agentDef;
+      // No agentDef = no restrictions (hook is a no-op).
+      if (!agentDef) return {};
+
+      const toolName = event.toolName ?? "";
+      const BLOCKED_TOOLS = ["Edit", "Write", "Bash"];
+
+      // ── W7b: Lead blocking ─────────────────────────────────────────────
+      // Only restrict agents whose CANT role is explicitly "lead".
+      // Non-lead roles (worker, orchestrator, undefined) pass this gate.
+      if (agentDef.role !== "lead") {
+        // Fall through to the T424 worker path ACL check below.
+      } else {
+        // Lead role: block Edit/Write/Bash entirely.
+        if (!BLOCKED_TOOLS.includes(toolName)) return {};
+
+        // Reject the tool call with a LAFS error envelope.
+        return {
+          rejected: true,
+          error: {
+            code: 70,
+            codeName: "E_LEAD_TOOL_BLOCKED",
+            message: `Lead agents cannot execute ${toolName} — dispatch to a worker instead`,
+            fix: "Use the delegate tool to spawn a worker agent for this work",
+          },
+        };
+      }
+
+      // ── T424: Worker path ACL ──────────────────────────────────────────
+      // Workers with declared file permissions can only write inside their
+      // declared globs. Applies to Edit, Write, and Bash (best-effort).
+      if (
+        agentDef.role === "worker" &&
+        agentDef.filePermissions !== undefined &&
+        BLOCKED_TOOLS.includes(toolName)
+      ) {
+        const writeGlobs = agentDef.filePermissions.write;
+        // `undefined` write field = no declared write ACL = allow through.
+        // Empty array [] = explicit no-writes = default-deny.
+        if (writeGlobs !== undefined) {
+          const targetPath = extractTargetPath(toolName, event.toolInput);
+          if (targetPath !== null && !matchesAnyGlob(targetPath, writeGlobs)) {
+            const agentName = agentDef.name ?? "worker";
+            const scopeList =
+              writeGlobs.length > 0 ? writeGlobs.join(", ") : "(none — this worker is read-only)";
+            return {
+              rejected: true,
+              error: {
+                code: 71,
+                codeName: "E_WORKER_PATH_ACL_VIOLATION",
+                message: `Worker ${agentName} is not allowed to write to ${targetPath}`,
+                fix:
+                  `This worker can only write inside: ${scopeList}. ` +
+                  "Either update the worker's permissions.files.write glob in " +
+                  ".cleo/teams.cant, or dispatch to a different worker with matching scope.",
+              },
+            };
+          }
+        }
+      }
+
+      return {};
+    },
+  );
+
+  // /cant:bundle-info — introspection command
+  pi.registerCommand("cant:bundle-info", {
+    description: "Show the state of the CANT bundle compiled at session start",
+    handler: async (
+      _args: string,
+      ctx: ExtensionContext & { hasUI: boolean; signal?: AbortSignal },
+    ) => {
+      const content = lastDiagnosticSummary
+        ? `CANT Bundle: ${lastDiagnosticSummary}`
+        : "CANT Bundle: no .cant files compiled (check .cleo/cant/ directory)";
+      pi.sendMessage(
+        { customType: "cleo-cant-bundle-info", content, display: true },
+        { triggerTurn: false },
+      );
+      if (ctx.hasUI) {
+        ctx.ui.notify(
+          lastDiagnosticSummary ? "CANT bundle loaded" : "No CANT bundle",
+          "info",
+        );
+      }
+    },
+  });
+
+  // session_shutdown: clear cached state
+  pi.on("session_shutdown", async () => {
+    bundlePrompt = null;
+    lastDiagnosticSummary = null;
+  });
+}

package/extensions/cleo-chatroom.ts

@@ -36,8 +36,14 @@ import { Type } from "@sinclair/typebox";
 // Message model
 // ---------------------------------------------------------------------------
 
+/**
+ * Tier role of an agent in the 3-tier hierarchy (ULTRAPLAN §10).
+ * Used to apply distinct TUI styling per tier.
+ */
+export type AgentTierRole = "orchestrator" | "lead" | "worker";
+
 /** A single inter-agent chat message. */
-interface ChatMessage {
+export interface ChatMessage {
   /** ISO-8601 timestamp of when the message was created. */
   timestamp: string;
   /** Name of the sending agent. */
@@ -48,6 +54,14 @@ interface ChatMessage {
   channel: "send_to_lead" | "broadcast_to_team" | "report_to_orchestrator" | "query_peer";
   /** The message text. */
   text: string;
+  /**
+   * Optional tier role of the sending agent.
+   *
+   * When present, the TUI row is prefixed and (if ANSI is available)
+   * coloured by tier: orchestrator = green ([O]), lead = yellow ([L]),
+   * worker = blue ([W]).  Defaults to "worker" when absent.
+   */
+  role?: AgentTierRole;
 }
 
 // ---------------------------------------------------------------------------
@@ -85,15 +99,40 @@ function recordMessage(msg: ChatMessage): void {
   }
 }
 
+/**
+ * Return the single-character tier prefix for a chat message row.
+ *
+ * - `[O]` orchestrator (green in ANSI-capable terminals)
+ * - `[L]` lead         (yellow)
+ * - `[W]` worker       (blue, default)
+ *
+ * @param role - The sending agent's tier role, or `undefined` to default to worker.
+ * @returns The three-character prefix string.
+ */
+export function tierPrefix(role: AgentTierRole | undefined): string {
+  switch (role) {
+    case "orchestrator":
+      return "[O]";
+    case "lead":
+      return "[L]";
+    default:
+      return "[W]";
+  }
+}
+
 /**
  * Format a chat message for TUI display.
  *
+ * Each row is prefixed with a tier indicator ([O]/[L]/[W]) so orchestrator,
+ * lead, and worker traffic is visually distinct in the chat panel (ULTRAPLAN §13).
+ *
  * @param msg - The message to format.
  * @returns A single-line string representation.
  */
-function formatMessage(msg: ChatMessage): string {
+export function formatMessage(msg: ChatMessage): string {
   const time = msg.timestamp.slice(11, 19);
-  return `[${time}] ${msg.from} -> ${msg.to}: ${msg.text}`;
+  const prefix = tierPrefix(msg.role);
+  return `${prefix} [${time}] ${msg.from} -> ${msg.to}: ${msg.text}`;
 }
 
 /**
@@ -123,12 +162,26 @@ const SendToLeadParams = Type.Object({
   message: Type.String({ description: "Message to send to your team lead" }),
   from: Type.String({ description: "Your agent name" }),
   lead: Type.String({ description: "Name of the lead agent" }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 const BroadcastToTeamParams = Type.Object({
   message: Type.String({ description: "Message to broadcast to the team" }),
   from: Type.String({ description: "Your agent name (lead)" }),
   group: Type.String({ description: "Team group name (e.g. 'backend')" }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 const ReportToOrchestratorParams = Type.Object({
@@ -137,12 +190,26 @@ const ReportToOrchestratorParams = Type.Object({
   orchestrator: Type.String({
     description: "Name of the orchestrator agent",
   }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 const QueryPeerParams = Type.Object({
   message: Type.String({ description: "Query for your peer worker" }),
   from: Type.String({ description: "Your agent name" }),
   peer: Type.String({ description: "Name of the peer worker to query" }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 // ---------------------------------------------------------------------------
@@ -194,7 +261,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: SendToLeadParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; lead: string },
+      params: { message: string; from: string; lead: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -205,6 +272,7 @@ export default function (pi: ExtensionAPI): void {
         to: params.lead,
         channel: "send_to_lead",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);
@@ -231,7 +299,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: BroadcastToTeamParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; group: string },
+      params: { message: string; from: string; group: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -242,6 +310,7 @@ export default function (pi: ExtensionAPI): void {
         to: `team:${params.group}`,
         channel: "broadcast_to_team",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);
@@ -268,7 +337,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: ReportToOrchestratorParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; orchestrator: string },
+      params: { message: string; from: string; orchestrator: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -279,6 +348,7 @@ export default function (pi: ExtensionAPI): void {
         to: params.orchestrator,
         channel: "report_to_orchestrator",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);
@@ -305,7 +375,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: QueryPeerParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; peer: string },
+      params: { message: string; from: string; peer: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -316,6 +386,7 @@ export default function (pi: ExtensionAPI): void {
         to: params.peer,
         channel: "query_peer",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo-os",
-  "version": "2026.4.12",
+  "version": "2026.4.16",
   "description": "CleoOS — the batteries-included agentic development environment wrapping Pi",
   "type": "module",
   "main": "./dist/cli.js",
@@ -8,8 +8,8 @@
     "cleoos": "dist/cli.js"
   },
   "dependencies": {
-    "@cleocode/cleo": "2026.4.12",
-    "@cleocode/cant": "2026.4.12"
+    "@cleocode/cant": "2026.4.16",
+    "@cleocode/cleo": "2026.4.16"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=0.60.0"
@@ -20,8 +20,8 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -41,8 +41,11 @@
     "bin"
   ],
   "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
+    "build": "tsc && tsc -p tsconfig.extensions.json && tsc -p tsconfig.postinstall.json",
+    "build:src": "tsc",
+    "build:extensions": "tsc -p tsconfig.extensions.json",
+    "build:postinstall": "tsc -p tsconfig.postinstall.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.extensions.json --noEmit && tsc -p tsconfig.postinstall.json --noEmit",
     "test": "vitest run",
     "postinstall": "node bin/postinstall.js"
   }