@phnx-labs/agents-cli 1.22.71 → 1.22.73

package/dist/lib/agent-spec/package-resolve.js

@@ -0,0 +1,274 @@
+/**
+ * Canonical agent-package resolver (PHNX-3838).
+ *
+ * `resolveAgentPackage` is the ONE place that decides what a package's logical
+ * resources are: it validates the manifest, resolves every declared resource
+ * path against the package directory (failing closed on anything missing,
+ * malformed, or escaping the package root), hashes each resource
+ * deterministically, and applies the package's conflict-resolution rule —
+ * within one scope (portable, or one harness's overlay) a duplicate
+ * `(kind, name)` is a hard validation error; across scopes, an overlay
+ * resource deterministically replaces the portable resource of the same
+ * `(kind, name)` when a harness materializes it (`effectiveResources`).
+ *
+ * This module never writes to disk and never knows about any specific
+ * harness's native format — `materialize.ts` is the only consumer of
+ * `effectiveResources`, and it owns projection, not resolution.
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { assertWithin, isSafeSegmentName } from '../paths.js';
+import { loadAgentPackageManifest } from './package-schema.js';
+import { AgentPackageError } from './package-types.js';
+/**
+ * Reject a package source that is a symlink, or that resolves (through a
+ * symlinked ancestor) outside the package's real root. `assertWithin` above is a
+ * TEXTUAL check — `path.resolve` normalizes `..` but never follows links — so a
+ * `skills/evil -> /home/user/.ssh` symlink, or an `instructions.md ->
+ * /etc/passwd` symlink, passes it while the actual bytes read/copied come from
+ * OUTSIDE the package. This is the containment check that makes the copy safe.
+ * A missing source is left for the `requireFile`/`requireDir` caller to report.
+ */
+function assertRealSourceWithin(abs, packageReal, label) {
+    let lst;
+    try {
+        lst = fs.lstatSync(abs);
+    }
+    catch {
+        return; // does not exist — requireFile/requireDir reports the specific error
+    }
+    if (lst.isSymbolicLink()) {
+        throw new AgentPackageError(`${label}: '${abs}' is a symlink; symlinked package sources are not allowed`, 'path-escape');
+    }
+    let real;
+    try {
+        real = fs.realpathSync(abs);
+    }
+    catch {
+        return;
+    }
+    if (real !== packageReal && !real.startsWith(packageReal + path.sep)) {
+        throw new AgentPackageError(`${label}: '${abs}' resolves outside the package directory`, 'path-escape');
+    }
+}
+function resolveWithin(containRoot, relPath, label, packageReal) {
+    const abs = path.resolve(containRoot, relPath);
+    try {
+        assertWithin(containRoot, abs);
+    }
+    catch {
+        throw new AgentPackageError(`${label}: '${relPath}' escapes the package directory`, 'path-escape');
+    }
+    assertRealSourceWithin(abs, packageReal, label);
+    return abs;
+}
+function sha256OfBytes(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+/** Deterministic combined hash of every file under `dir`, sorted by relative path. */
+function sha256OfDir(dir) {
+    const files = [];
+    const walk = (base) => {
+        for (const entry of fs.readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isSymbolicLink())
+                continue;
+            const full = path.join(base, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile())
+                files.push(full);
+        }
+    };
+    walk(dir);
+    const hash = crypto.createHash('sha256');
+    for (const file of files) {
+        const rel = path.relative(dir, file).split(path.sep).join('/');
+        hash.update(rel).update('\0').update(fs.readFileSync(file)).update('\n');
+    }
+    return hash.digest('hex');
+}
+function requireFile(absPath, label) {
+    let stat;
+    try {
+        stat = fs.statSync(absPath);
+    }
+    catch {
+        throw new AgentPackageError(`${label}: no such file '${absPath}'`, 'invalid-resource');
+    }
+    if (!stat.isFile()) {
+        throw new AgentPackageError(`${label}: '${absPath}' is not a file`, 'invalid-resource');
+    }
+}
+function requireDir(absPath, label) {
+    let stat;
+    try {
+        stat = fs.statSync(absPath);
+    }
+    catch {
+        throw new AgentPackageError(`${label}: no such directory '${absPath}'`, 'invalid-resource');
+    }
+    if (!stat.isDirectory()) {
+        throw new AgentPackageError(`${label}: '${absPath}' is not a directory`, 'invalid-resource');
+    }
+}
+function parseYamlFile(absPath, label) {
+    let raw;
+    try {
+        raw = fs.readFileSync(absPath, 'utf-8');
+    }
+    catch (err) {
+        throw new AgentPackageError(`${label}: cannot read '${absPath}' — ${err.message}`, 'invalid-resource');
+    }
+    try {
+        return yaml.parse(raw);
+    }
+    catch (err) {
+        throw new AgentPackageError(`${label}: malformed YAML in '${absPath}' — ${err.message}`, 'invalid-resource');
+    }
+}
+function resolveInstructions(packageDir, relPath, provenance, label, packageReal) {
+    const abs = resolveWithin(packageDir, relPath, label, packageReal);
+    requireFile(abs, label);
+    return { kind: 'instructions', name: 'instructions', sourcePath: abs, sha256: sha256OfBytes(fs.readFileSync(abs)), provenance };
+}
+function resolveDirResource(packageDir, relPath, kind, markerFile, provenance, label, packageReal) {
+    const abs = resolveWithin(packageDir, relPath, label, packageReal);
+    requireDir(abs, label);
+    requireFile(path.join(abs, markerFile), `${label} (missing ${markerFile})`);
+    return { kind, name: path.basename(abs), sourcePath: abs, sha256: sha256OfDir(abs), provenance };
+}
+function resolveMcpResource(packageDir, relPath, provenance, label, packageReal) {
+    const abs = resolveWithin(packageDir, relPath, label, packageReal);
+    requireFile(abs, label);
+    const server = parseYamlFile(abs, label);
+    if (!server || typeof server.name !== 'string' || server.name.length === 0) {
+        throw new AgentPackageError(`${label}: '${relPath}' must declare a 'name'`, 'invalid-resource');
+    }
+    if (server.transport !== 'stdio' && server.transport !== 'http' && server.transport !== 'sse') {
+        throw new AgentPackageError(`${label}: '${relPath}' has an invalid transport (${JSON.stringify(server.transport)})`, 'invalid-resource');
+    }
+    if (server.transport === 'stdio' && !server.command) {
+        throw new AgentPackageError(`${label}: '${relPath}' declares transport 'stdio' but no 'command'`, 'invalid-resource');
+    }
+    if ((server.transport === 'http' || server.transport === 'sse') && !server.url) {
+        throw new AgentPackageError(`${label}: '${relPath}' declares transport '${server.transport}' but no 'url'`, 'invalid-resource');
+    }
+    return {
+        kind: 'mcp',
+        name: server.name,
+        sourcePath: abs,
+        sha256: sha256OfBytes(fs.readFileSync(abs)),
+        provenance,
+        mcp: server,
+    };
+}
+function resolveHookResource(packageDir, relPath, provenance, label, packageReal) {
+    const abs = resolveWithin(packageDir, relPath, label, packageReal);
+    requireFile(abs, label);
+    const hook = parseYamlFile(abs, label);
+    if (!hook || typeof hook.name !== 'string' || hook.name.length === 0) {
+        throw new AgentPackageError(`${label}: '${relPath}' must declare a 'name'`, 'invalid-resource');
+    }
+    // The hook name becomes a filename in the materialized home, so a traversing
+    // name ('../../foo') would write a hook script outside the output home. Reject
+    // anything but a single safe path segment at the source.
+    if (!isSafeSegmentName(hook.name)) {
+        throw new AgentPackageError(`${label}: hook name '${hook.name}' is not a safe single path segment`, 'invalid-resource');
+    }
+    if (typeof hook.script !== 'string' || hook.script.length === 0) {
+        throw new AgentPackageError(`${label}: '${relPath}' must declare a 'script'`, 'invalid-resource');
+    }
+    if (!Array.isArray(hook.events) || hook.events.length === 0 || hook.events.some((e) => typeof e !== 'string')) {
+        throw new AgentPackageError(`${label}: '${relPath}' must declare a non-empty 'events' list of strings`, 'invalid-resource');
+    }
+    const scriptPath = resolveWithin(path.dirname(abs), hook.script, label, packageReal);
+    requireFile(scriptPath, `${label} (hook script)`);
+    return {
+        kind: 'hooks',
+        name: hook.name,
+        sourcePath: abs,
+        sha256: sha256OfBytes(Buffer.concat([fs.readFileSync(abs), Buffer.from('\0'), fs.readFileSync(scriptPath)])),
+        provenance,
+        hook: { def: hook, scriptPath },
+    };
+}
+function assertNoDuplicates(resources, scopeLabel) {
+    const seen = new Map();
+    for (const r of resources) {
+        const key = `${r.kind}:${r.name}`;
+        const prior = seen.get(key);
+        if (prior) {
+            throw new AgentPackageError(`${scopeLabel}: duplicate ${r.kind} '${r.name}' declared by both '${prior.sourcePath}' and '${r.sourcePath}'`, 'duplicate-resource');
+        }
+        seen.set(key, r);
+    }
+}
+function resolveScope(packageDir, paths, provenance, scopeLabel, packageReal) {
+    const resources = [];
+    if (paths.instructions)
+        resources.push(resolveInstructions(packageDir, paths.instructions, provenance, scopeLabel, packageReal));
+    for (const p of paths.skills)
+        resources.push(resolveDirResource(packageDir, p, 'skills', 'SKILL.md', provenance, scopeLabel, packageReal));
+    for (const p of paths.subagents)
+        resources.push(resolveDirResource(packageDir, p, 'subagents', 'AGENT.md', provenance, scopeLabel, packageReal));
+    for (const p of paths.mcp)
+        resources.push(resolveMcpResource(packageDir, p, provenance, scopeLabel, packageReal));
+    for (const p of paths.hooks)
+        resources.push(resolveHookResource(packageDir, p, provenance, scopeLabel, packageReal));
+    // Sort deterministically — resolution order in agent.yaml must not affect output.
+    resources.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind.localeCompare(b.kind)));
+    assertNoDuplicates(resources, scopeLabel);
+    return resources;
+}
+/** Deterministic package identity digest — independent of which harness later materializes it. */
+function computeDigest(portable, overlays) {
+    const hash = crypto.createHash('sha256');
+    const record = (label, resources) => {
+        for (const r of resources)
+            hash.update(`${label}\0${r.kind}\0${r.name}\0${r.sha256}\n`);
+    };
+    record('portable', portable);
+    for (const agent of Object.keys(overlays).sort())
+        record(`overlay:${agent}`, overlays[agent] ?? []);
+    return hash.digest('hex');
+}
+/** Parse, validate, and resolve every declared resource of a package directory into one canonical result. */
+export function resolveAgentPackage(packageDir) {
+    const manifest = loadAgentPackageManifest(packageDir);
+    const ex = manifest.execution;
+    // The package's REAL root — every resource source must realpath-resolve under
+    // this, so a symlinked ancestor can't smuggle in bytes from outside. The
+    // manifest already loaded from packageDir, so it exists and realpath succeeds.
+    const packageReal = fs.realpathSync(path.resolve(packageDir));
+    const portable = resolveScope(packageDir, { instructions: ex.instructions, skills: ex.skills, subagents: ex.subagents, mcp: ex.mcp, hooks: ex.hooks }, 'portable', 'execution', packageReal);
+    const overlays = {};
+    for (const [agent, overlay] of Object.entries(ex.harnessOverlays)) {
+        overlays[agent] = resolveScope(packageDir, { instructions: overlay.instructions, skills: overlay.skills ?? [], subagents: overlay.subagents ?? [], mcp: overlay.mcp ?? [], hooks: overlay.hooks ?? [] }, 'overlay', `execution.harness_overlays.${agent}`, packageReal);
+    }
+    return {
+        manifest,
+        packageDir: path.resolve(packageDir),
+        digest: computeDigest(portable, overlays),
+        portable,
+        overlays,
+    };
+}
+/**
+ * The resource set a specific harness actually materializes: portable
+ * resources, with any harness-overlay resource of the same `(kind, name)`
+ * deterministically replacing its portable counterpart, plus overlay-only
+ * additions. This is the ONE merge rule every harness adapter shares —
+ * `materialize.ts` calls this instead of re-deriving precedence per harness.
+ */
+export function effectiveResources(resolved, harness) {
+    const overlay = resolved.overlays[harness] ?? [];
+    const overlayKeys = new Set(overlay.map((r) => `${r.kind}:${r.name}`));
+    const merged = [
+        ...resolved.portable.filter((r) => !overlayKeys.has(`${r.kind}:${r.name}`)),
+        ...overlay,
+    ];
+    merged.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind.localeCompare(b.kind)));
+    return merged;
+}

package/dist/lib/agent-spec/package-schema.d.ts

@@ -0,0 +1,5 @@
+import type { AgentPackageManifest } from './package-types.js';
+/** Parse and shape-validate the `execution` block of a schema-v3 agent.yaml already read into memory. */
+export declare function parseAgentPackageManifest(raw: unknown, sourceLabel: string): AgentPackageManifest;
+/** Read + parse `<packageDir>/agent.yaml`. Fails closed on missing file or malformed YAML. */
+export declare function loadAgentPackageManifest(packageDir: string): AgentPackageManifest;

package/dist/lib/agent-spec/package-schema.js

@@ -0,0 +1,147 @@
+/**
+ * Schema-v3 `execution` block parsing for a portable agent package (agent.yaml).
+ *
+ * Pure and fs-free beyond reading the manifest file itself — never resolves or
+ * hashes referenced resources (that's `package-resolve.ts`). Fails closed on
+ * anything malformed: this is the "malformed shared config fails closed"
+ * boundary from the PHNX-3838 brief, so a bad manifest throws immediately
+ * rather than materializing a partial package.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { ALL_AGENT_IDS } from './agents.js';
+import { AgentPackageError } from './package-types.js';
+const AGENT_ID_SET = new Set(ALL_AGENT_IDS);
+function isAgentId(value) {
+    return typeof value === 'string' && AGENT_ID_SET.has(value);
+}
+function fail(message, details) {
+    throw new AgentPackageError(message, 'invalid-manifest', details);
+}
+function stringArray(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        fail(`agent.yaml: '${field}' must be a list of strings`);
+    }
+    return value;
+}
+function parseHarnessOverlay(raw, agent) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        fail(`agent.yaml: execution.harness_overlays.${agent} must be a mapping`);
+    }
+    const r = raw;
+    if (r.instructions !== undefined && typeof r.instructions !== 'string') {
+        fail(`agent.yaml: execution.harness_overlays.${agent}.instructions must be a string`);
+    }
+    return {
+        instructions: r.instructions,
+        skills: stringArray(r.skills, `execution.harness_overlays.${agent}.skills`),
+        subagents: stringArray(r.subagents, `execution.harness_overlays.${agent}.subagents`),
+        mcp: stringArray(r.mcp, `execution.harness_overlays.${agent}.mcp`),
+        hooks: stringArray(r.hooks, `execution.harness_overlays.${agent}.hooks`),
+    };
+}
+/** Parse and shape-validate the `execution` block of a schema-v3 agent.yaml already read into memory. */
+export function parseAgentPackageManifest(raw, sourceLabel) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        fail(`${sourceLabel}: expected a YAML mapping at the document root`);
+    }
+    const doc = raw;
+    if (doc.schema_version !== 3) {
+        fail(`${sourceLabel}: schema_version must be 3 (got ${JSON.stringify(doc.schema_version)}) — this resolver only understands schema v3 execution blocks`);
+    }
+    if ('http_tools' in doc) {
+        fail(`${sourceLabel}: 'http_tools' is forbidden at schema v3 — use execution.mcp instead`);
+    }
+    if (typeof doc.name !== 'string' || doc.name.length === 0) {
+        fail(`${sourceLabel}: 'name' is required and must be a non-empty string`);
+    }
+    if (typeof doc.slug !== 'string' || doc.slug.length === 0) {
+        fail(`${sourceLabel}: 'slug' is required and must be a non-empty string`);
+    }
+    if (doc.description !== undefined && typeof doc.description !== 'string') {
+        fail(`${sourceLabel}: 'description' must be a string`);
+    }
+    const execution = doc.execution;
+    if (execution === null || typeof execution !== 'object' || Array.isArray(execution)) {
+        fail(`${sourceLabel}: 'execution' block is required`);
+    }
+    const ex = execution;
+    const mode = ex.mode;
+    if (mode !== 'cloud' && mode !== 'local') {
+        fail(`${sourceLabel}: execution.mode must be 'cloud' or 'local' (got ${JSON.stringify(mode)})`);
+    }
+    const harnesses = ex.harnesses;
+    if (harnesses === null || typeof harnesses !== 'object' || Array.isArray(harnesses)) {
+        fail(`${sourceLabel}: execution.harnesses is required`);
+    }
+    const h = harnesses;
+    if (!isAgentId(h.default)) {
+        fail(`${sourceLabel}: execution.harnesses.default must name a known agent id (got ${JSON.stringify(h.default)})`);
+    }
+    const supportedRaw = stringArray(h.supported, 'execution.harnesses.supported');
+    if (supportedRaw.length === 0) {
+        fail(`${sourceLabel}: execution.harnesses.supported must list at least one agent id`);
+    }
+    const badIds = supportedRaw.filter((id) => !isAgentId(id));
+    if (badIds.length > 0) {
+        fail(`${sourceLabel}: execution.harnesses.supported names unknown agent id(s): ${badIds.join(', ')}`);
+    }
+    const supported = supportedRaw;
+    if (!supported.includes(h.default)) {
+        fail(`${sourceLabel}: execution.harnesses.default (${String(h.default)}) must also appear in execution.harnesses.supported`);
+    }
+    if (typeof ex.instructions !== 'string' || ex.instructions.length === 0) {
+        fail(`${sourceLabel}: execution.instructions is required and must be a non-empty relative path`);
+    }
+    const harnessOverlaysRaw = ex.harness_overlays;
+    const harnessOverlays = {};
+    if (harnessOverlaysRaw !== undefined) {
+        if (harnessOverlaysRaw === null || typeof harnessOverlaysRaw !== 'object' || Array.isArray(harnessOverlaysRaw)) {
+            fail(`${sourceLabel}: execution.harness_overlays must be a mapping`);
+        }
+        for (const [agent, overlay] of Object.entries(harnessOverlaysRaw)) {
+            if (!isAgentId(agent)) {
+                fail(`${sourceLabel}: execution.harness_overlays names unknown agent id: ${agent}`);
+            }
+            harnessOverlays[agent] = parseHarnessOverlay(overlay, agent);
+        }
+    }
+    return {
+        schemaVersion: 3,
+        name: doc.name,
+        slug: doc.slug,
+        description: doc.description,
+        execution: {
+            mode,
+            harnesses: { default: h.default, supported },
+            instructions: ex.instructions,
+            skills: stringArray(ex.skills, 'execution.skills'),
+            subagents: stringArray(ex.subagents, 'execution.subagents'),
+            mcp: stringArray(ex.mcp, 'execution.mcp'),
+            hooks: stringArray(ex.hooks, 'execution.hooks'),
+            harnessOverlays,
+        },
+    };
+}
+/** Read + parse `<packageDir>/agent.yaml`. Fails closed on missing file or malformed YAML. */
+export function loadAgentPackageManifest(packageDir) {
+    const manifestPath = path.join(packageDir, 'agent.yaml');
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, 'utf-8');
+    }
+    catch {
+        throw new AgentPackageError(`agent.yaml not found in ${packageDir}`, 'invalid-manifest');
+    }
+    let doc;
+    try {
+        doc = yaml.parse(raw);
+    }
+    catch (err) {
+        throw new AgentPackageError(`${manifestPath}: malformed YAML — ${err.message}`, 'invalid-manifest');
+    }
+    return parseAgentPackageManifest(doc, manifestPath);
+}

package/dist/lib/agent-spec/package-types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Types for the portable agent-package resolver + native-home materializer
+ * (PHNX-3838). A package is a filesystem `agent.yaml` (schema v3 `execution`
+ * block) describing behavior — instructions, skills, subagents, mcp, hooks —
+ * that `resolveAgentPackage` reduces to ONE canonical resource set, which
+ * `materializeAgentPackage` then projects into a native Claude Code, Codex, or
+ * OpenCode home. See `.agents/plans/phnx-3827-portable-agent-cloud/plan.md`
+ * (PR muqsitnawaz/agents#2055) for the source design.
+ */
+import type { AgentId } from '../types.js';
+export type PackageResourceKind = 'instructions' | 'skills' | 'subagents' | 'mcp' | 'hooks';
+/** Where a resolved resource came from — the provenance a conflict resolution decision needs. */
+export type ResourceProvenance = 'portable' | 'overlay';
+/** Thrown on any bad package or unsatisfiable materialization request. Never `process.exit`. */
+export declare class AgentPackageError extends Error {
+    readonly code: 'invalid-manifest' | 'invalid-resource' | 'duplicate-resource' | 'path-escape' | 'unsupported-harness' | 'unsupported-capability';
+    readonly details?: string[] | undefined;
+    constructor(message: string, code: 'invalid-manifest' | 'invalid-resource' | 'duplicate-resource' | 'path-escape' | 'unsupported-harness' | 'unsupported-capability', details?: string[] | undefined);
+}
+/** One MCP server declared by a package's `mcp/*.yaml` resource file. */
+export interface PackageMcpServer {
+    name: string;
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/** One lifecycle hook declared by a package's `hooks/*.yaml` resource file. */
+export interface PackageHook {
+    name: string;
+    /** Path to the hook's script, relative to the hook manifest's own directory. */
+    script: string;
+    events: string[];
+    matcher?: string;
+    timeout?: number;
+}
+/** A harness-scoped overlay: the same resource-directory shape as the package root. */
+export interface PackageHarnessOverlay {
+    instructions?: string;
+    skills?: string[];
+    subagents?: string[];
+    mcp?: string[];
+    hooks?: string[];
+}
+/** Parsed + shape-validated `execution` block of a schema-v3 `agent.yaml`. */
+export interface AgentPackageManifest {
+    schemaVersion: 3;
+    name: string;
+    slug: string;
+    description?: string;
+    execution: {
+        mode: 'cloud' | 'local';
+        harnesses: {
+            default: AgentId;
+            supported: AgentId[];
+        };
+        instructions: string;
+        skills: string[];
+        subagents: string[];
+        mcp: string[];
+        hooks: string[];
+        harnessOverlays: Partial<Record<AgentId, PackageHarnessOverlay>>;
+    };
+}
+/** One resource in the canonical, resolved package — before harness projection. */
+export interface ResolvedResource {
+    kind: PackageResourceKind;
+    /** Stable resource name within its kind (skill/subagent/mcp-server/hook name, or 'instructions'). */
+    name: string;
+    /** Absolute path to the resource's source — a file for instructions/mcp/hooks, a dir for skills/subagents. */
+    sourcePath: string;
+    /** Deterministic content hash — a single file's sha256, or a directory's combined sha256. */
+    sha256: string;
+    provenance: ResourceProvenance;
+    /** Parsed definition, kind === 'mcp' only. */
+    mcp?: PackageMcpServer;
+    /** Parsed definition + resolved script path, kind === 'hooks' only. */
+    hook?: {
+        def: PackageHook;
+        scriptPath: string;
+    };
+}
+/** The one canonical resolution of a package: portable resources plus each harness's overlay. */
+export interface ResolvedAgentPackage {
+    manifest: AgentPackageManifest;
+    packageDir: string;
+    /** Deterministic digest over every declared resource (portable + all overlays), independent of harness. */
+    digest: string;
+    portable: ResolvedResource[];
+    overlays: Partial<Record<AgentId, ResolvedResource[]>>;
+}
+export interface MaterializationReceiptEntry {
+    kind: PackageResourceKind;
+    name: string;
+    /** Path the materializer wrote, relative to the output home. */
+    target: string;
+    sha256: string;
+    provenance: ResourceProvenance;
+}
+export interface MaterializationReceipt {
+    schemaVersion: 1;
+    agent: {
+        ref: string;
+        digest: string;
+    };
+    harness: {
+        id: AgentId;
+        version: string;
+    };
+    resources: MaterializationReceiptEntry[];
+    warnings: string[];
+}
+export interface MaterializeOptions {
+    harness: AgentId;
+    /** Harness version — gates per-kind capability support (e.g. codex hooks need >= 0.116.0). */
+    harnessVersion: string;
+    /** Absolute path to the fresh, isolated home to materialize into. Created if missing. */
+    outputHome: string;
+}

package/dist/lib/agent-spec/package-types.js

@@ -0,0 +1,11 @@
+/** Thrown on any bad package or unsatisfiable materialization request. Never `process.exit`. */
+export class AgentPackageError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'AgentPackageError';
+    }
+}

package/dist/lib/daemon/usage-sync-service.d.ts

@@ -1,10 +1,17 @@
 /**
- * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ * Fleet shared-state sync as a `PeriodicService` (PHNX-3392 usage-sync,
+ * PHNX-3792 session mirror).
  *
- * A headed box publishes its local identity-keyed Claude usage rows into its
- * owned file in the fleet-synced user repo. The tick then runs one serialized,
- * timeout-bounded git exchange; a worker reads the delivered peer snapshots
- * and merges newest-wins. No tick opens a device-to-device SSH mesh.
+ * This is the one tick that owns the bounded Git exchange over the fleet-synced
+ * user repo, so every non-secret daemon-state field rides it rather than opening
+ * a second committer. Each tick: (1) publishes this box's own fields into its
+ * conflict-free `devices/<device>/daemon-state.json` — a headed box's Claude
+ * usage snapshot, and EVERY box's lightweight session digests (PHNX-3792);
+ * (2) runs one serialized, timeout-bounded commit/rebase/push; (3) consumes the
+ * peer fields the exchange delivered — a worker merges usage newest-wins, and
+ * every non-worker box folds peers' session digests into its local index so the
+ * picker renders remote-host previews inline. No tick opens a device-to-device
+ * SSH mesh.
  */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';

package/dist/lib/daemon/usage-sync-service.js

@@ -1,10 +1,17 @@
 /**
- * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ * Fleet shared-state sync as a `PeriodicService` (PHNX-3392 usage-sync,
+ * PHNX-3792 session mirror).
  *
- * A headed box publishes its local identity-keyed Claude usage rows into its
- * owned file in the fleet-synced user repo. The tick then runs one serialized,
- * timeout-bounded git exchange; a worker reads the delivered peer snapshots
- * and merges newest-wins. No tick opens a device-to-device SSH mesh.
+ * This is the one tick that owns the bounded Git exchange over the fleet-synced
+ * user repo, so every non-secret daemon-state field rides it rather than opening
+ * a second committer. Each tick: (1) publishes this box's own fields into its
+ * conflict-free `devices/<device>/daemon-state.json` — a headed box's Claude
+ * usage snapshot, and EVERY box's lightweight session digests (PHNX-3792);
+ * (2) runs one serialized, timeout-bounded commit/rebase/push; (3) consumes the
+ * peer fields the exchange delivered — a worker merges usage newest-wins, and
+ * every non-worker box folds peers' session digests into its local index so the
+ * picker renders remote-host previews inline. No tick opens a device-to-device
+ * SSH mesh.
  */
 import { BasePeriodicService } from './service.js';
 const USAGE_SYNC_TICK_MS = 15 * 60_000;
@@ -23,11 +30,18 @@ export class UsageSyncService extends BasePeriodicService {
     }
     async onTick(ctx) {
         const { consumeUsageSnapshotsFromSharedStore, publishUsageSnapshotToSharedStore } = await import('../accounting/usage-sync.js');
+        const { consumeSessionMirrorFromSharedStore, publishSessionMirrorToSharedStore } = await import('../session/mirror.js');
+        // Publish every owned field BEFORE the single git exchange so they ride one commit.
         const published = await publishUsageSnapshotToSharedStore();
         if (published.changed)
             ctx.log('INFO', `usage-sync: published usage snapshot to ${published.path}`);
         if (published.error)
             ctx.log('WARN', `usage-sync: publish: ${published.error}`);
+        const mirrored = await publishSessionMirrorToSharedStore();
+        if (mirrored.changed)
+            ctx.log('INFO', `session-mirror: published ${mirrored.count} session digest(s)`);
+        if (mirrored.error)
+            ctx.log('WARN', `session-mirror: publish: ${mirrored.error}`);
         const { syncFleetSharedStateRepo } = await import('../fleet-shared-repo-sync.js');
         const transport = await syncFleetSharedStateRepo();
         if (transport.skipped)
@@ -42,5 +56,13 @@ export class UsageSyncService extends BasePeriodicService {
         }
         for (const err of consumed.errors)
             ctx.log('WARN', `usage-sync: ${err.device}: ${err.message}`);
+        const foldedIn = consumeSessionMirrorFromSharedStore();
+        if (foldedIn.merged > 0) {
+            ctx.log('INFO', `session-mirror: folded ${foldedIn.merged} session(s) from ${foldedIn.sources.join(', ')}`);
+        }
+        if (foldedIn.pruned > 0)
+            ctx.log('INFO', `session-mirror: pruned ${foldedIn.pruned} stale mirror row(s)`);
+        for (const err of foldedIn.errors)
+            ctx.log('WARN', `session-mirror: ${err.device}: ${err.message}`);
     }
 }

package/dist/lib/exec.js

@@ -1166,6 +1166,7 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
                     sessionId: passthroughSessionId,
                     actor: resolveActor().id,
                     initiatedBy: resolveActor().kind,
+                    phoenixId: resolveActor().phoenixId,
                     startedAtMs: Date.now(),
                 });
             }
@@ -1564,6 +1565,7 @@ async function runInTmux(options, executable, args) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                phoenixId: resolveActor().phoenixId,
                 harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });
@@ -1899,6 +1901,7 @@ async function spawnAgent(options) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                phoenixId: resolveActor().phoenixId,
                 harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });