@fastagent-sh/fastagent 0.16.1 → 0.17.0

package/dist/deploy/agentcore/plan.js

@@ -29,19 +29,42 @@
  */
 import { createHash } from "node:crypto";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
+import { SECRETS_DIRNAME } from "../../paths.js";
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 /** SessionStorage mount = FASTAGENT_STATE_DIR (AgentCore requires exactly `/mnt/<one-level>`). It is
  *  a fast LOCAL disk only: the platform wipes it on every runtime version update (= every deploy).
  *  Durability across deploys comes from the S3 snapshot (channels/agentcore-state.ts). */
 export const MOUNT = "/mnt/state";
+/**
+ * FASTAGENT_SECRETS_DIR — the seeded-then-ROTATED auth.json, deliberately INSIDE the state root
+ * rather than beside it.
+ *
+ * Every other host mounts a real volume and puts the two machinery dirs side by side (`/data/.state`
+ * + `/data/.secrets`), because there the persistence boundary is the MOUNT POINT: anything under it
+ * survives. AgentCore has no volume. Its persistence boundary is `packStateRoot(stateRoot)` — the one
+ * directory tree the S3 snapshot copies out and back (channels/agentcore-state.ts) — while {@link MOUNT}
+ * itself is wiped on every runtime version update, i.e. on every deploy.
+ *
+ * So the sibling layout would put credentials INSIDE the mount but OUTSIDE the snapshot: nothing
+ * copies them out, the platform wipes them, and the next microVM re-seeds the deploy-time copy. With
+ * single-use OAuth refresh tokens that is a slow-motion outage — the box works until the seeded token
+ * is rotated away, then loses model access with only a redeploy to restore it.
+ *
+ * Nesting is what makes agentcore-state.ts's stated contract ("restores VERBATIM — including
+ * auth.json") reachable at all; `packStateRoot` walks the whole tree, so no snapshot code knows about
+ * this. Tests assert the containment, not just the two names — the sibling spelling looks tidier and
+ * reintroduces the outage silently.
+ */
+export const SECRETS_DIR = `${MOUNT}/${SECRETS_DIRNAME}`;
 /**
  * How long an idle session keeps its microVM. Memory is billed per second across the WHOLE session
  * — idle included, at the peak level reached — so this tail is the standing cost of every burst of
  * activity, while CPU stops billing the moment the agent stops working. 3 minutes rather than the
  * platform's 15: the tail shrinks 5×, and the cost is a cold start (image + Node + snapshot restore)
- * for anyone who returns after a longer gap. `/ping` reports HealthyBusy while work is in flight, so
- * this timer only ever starts once the agent has genuinely settled — a long turn is never cut short.
+ * for anyone who returns after a longer gap. `/ping` reports HealthyBusy + time_of_last_update while
+ * work is in flight (the FIELD is what the platform's idle measurement actually reads — agentcore.ts),
+ * so this timer only ever starts once the agent has genuinely settled — a long turn is never cut short.
  * AWS accepts 60–28800.
  */
 export const IDLE_TIMEOUT_SECONDS = 180;
@@ -72,6 +95,13 @@ export const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agent
 export function isGeneratedAgentcoreTemplate(content) {
     return content.startsWith(GENERATED_TEMPLATE_MARKER);
 }
+/** Deployment base name from the workspace basename — the ONE mapping used to find its stack later. */
+export function agentcoreName(workspaceBasename) {
+    return (workspaceBasename
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "agent");
+}
 /** Runtime name (`[a-zA-Z][a-zA-Z0-9_]{0,47}`) from a dir basename. */
 export function toRuntimeName(basename) {
     const slug = basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
@@ -437,6 +467,10 @@ function template(input, translated) {
         `        PORT: "8080"`, // the Runtime service contract's fixed port (config.http.port does not apply here)
         `        FASTAGENT_AGENTCORE: "1"`, // serve mounts /invocations + /ping, arms no resident cron
         `        FASTAGENT_STATE_DIR: ${MOUNT}`,
+        // Inside the state root on purpose — the snapshot is this host's only durable store, and it copies
+        // exactly one tree. See {@link SECRETS_DIR}: the sibling layout every other host uses would leave a
+        // rotated OAuth credential outside it, i.e. discarded with the microVM.
+        `        FASTAGENT_SECRETS_DIR: ${SECRETS_DIR}`,
     ];
     // The auth seed is chunked (env values max 2048 chars — see AUTH_SEED_CHUNK_SIZE): N parameters,
     // each riding its own env var; `start` reassembles them (collectAuthSeed). Empty defaults = unused.
@@ -529,7 +563,7 @@ function template(input, translated) {
         `      # forces a NAT gateway for model/channel egress (~$33/mo) — deliberately not the default.`,
         `      FilesystemConfigurations:`,
         `        - SessionStorage: { MountPath: ${MOUNT} }`,
-        `      # Idle ${IDLE_TIMEOUT_SECONDS}s (the ping's HealthyBusy keeps BUSY sessions alive regardless), max compute`,
+        `      # Idle ${IDLE_TIMEOUT_SECONDS}s (the ping's HealthyBusy + time_of_last_update keeps BUSY sessions alive), max compute`,
         `      # lifetime ${MAX_LIFETIME_SECONDS}s — the platform ceiling; the session id stays valid, so the next invoke`,
         `      # just gets fresh compute with the same storage. Memory bills per second for the whole`,
         `      # session INCLUDING the idle tail, so a shorter tail is the main cost lever here.`,
@@ -679,7 +713,12 @@ export function planAgentcoreDeploy(input) {
         ? `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`
         : `# 4. Read the outputs (the runtime ARN — this topology has NO public URL: nothing outside AWS`, ...(needsFunctionUrl
         ? []
-        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`);
+        : [`#    sends to it, so no Function URL is created and the agent is reachable only via SigV4).`]), `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, ...(needsForwarder
+        ? [
+            `# The ingress transport is a separate Lambda and therefore a separate log source:`,
+            `fastagent logs agentcore --source forwarder --follow`,
+        ]
+        : []));
     // Model-auth guidance mirrors the other hosts: an env key became a parameter above; OAuth/stored
     // can't be read at plan time — `--run` carries it as FastagentAuthSeed.
     if (!isEnvKey(input.modelAuth)) {
@@ -694,7 +733,7 @@ export function planAgentcoreDeploy(input) {
         post.push(`# Register the Telegram webhook (default route POST /telegram; secret_token MUST equal TELEGRAM_SECRET_TOKEN):`, `curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \\`, `  -d url=<ForwarderUrl>/telegram -d secret_token=<TELEGRAM_SECRET_TOKEN>`);
     }
     if (channels.includes("github")) {
-        post.push(`# Set the GitHub webhook (repo Settings → Webhooks): Payload URL = <ForwarderUrl>/webhook,`, `#   content type application/json, secret = GITHUB_WEBHOOK_SECRET.`, `# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy holds the session while turns run, but the 8 h compute ceiling is hard).`);
+        post.push(`# Set the GitHub webhook (repo Settings → Webhooks): Payload URL = <ForwarderUrl>/webhook,`, `#   content type application/json, secret = GITHUB_WEBHOOK_SECRET.`, `# NOTE: github turns are fire-and-forget with no replay — a compute reclaimed mid-review drops it`, `#   (the ping's HealthyBusy + time_of_last_update holds the session while turns run, but the 8 h compute ceiling is hard).`);
     }
     if (channels.includes("slack")) {
         post.push(`# Set Slack Event Subscriptions → Request URL = <ForwarderUrl>/slack (scopes per channels/slack.ts).`);
@@ -716,6 +755,6 @@ export function planAgentcoreDeploy(input) {
     if (needsForwarder) {
         runbook.push(``, `# After a REDEPLOY, stop the ingress session so the new image serves immediately — a live session`, `# keeps its old compute (and the OLD image) until ${IDLE_TIMEOUT_SECONDS}s idle / the 8 h compute ceiling`, `# (\`--run\` does this automatically):`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`);
     }
-    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`);
+    runbook.push(``, `# Redeploy = step 1b (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is a LOCAL disk — AWS wipes it on every runtime version update (i.e. every`, `# deploy) and after 14 idle days. What survives is the S3 snapshot under s3://${bucketHint}/${STATE_KEY}:`, `# the container restores it on its first invocation and pushes it whenever work settles. Keep that`, `# bucket and the agent keeps its sessions, channel state and pending wake-ups across deploys;`, `# delete it and the agent starts blank. (A persistent MOUNT would need EFS + VPC mode + a NAT`, `# gateway for model/channel egress — see the template comment.)`, `# CREDENTIALS RIDE THAT SNAPSHOT TOO: FASTAGENT_SECRETS_DIR is ${SECRETS_DIR}, inside the state`, `# root, so an OAuth auth.json ROTATED on the box persists (a refresh token is single-use — without`, `# this the next microVM would re-seed the deploy-time copy and eventually fail to authenticate).`, `# The bucket is therefore credential storage: it is created with public access blocked and`, `# versioning on, and deleting it costs model access until the next deploy re-seeds.`);
     return { artifacts, runbook, untranslatableSchedules: untranslatable };
 }

package/dist/deploy/container.js

@@ -128,8 +128,10 @@ CMD ["./${into("node_modules/.bin/fastagent")}", "start", "/app"]
 /** Patterns are RECURSIVE (`**​/`) on purpose — dockerignore patterns are root-anchored (unlike
  *  .gitignore), and a baked workspace can hold nested projects: a bare `node_modules` would upload
  *  their build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the
- *  image. `.secrets`/`.state` are fastagent machinery — secrets travel through the host's secret
- *  store, state lives on the volume; neither may ever enter an image. `.cache` is generic hygiene
+ *  image. `.secrets`/`.state` are fastagent machinery — credential contents travel through the host's
+ *  secret store and state lives on the volume, so neither may enter an image. The two tracked secrets
+ *  scaffolds (`.env.example` + `.gitignore`) are the narrow exception: they carry no values and must stay
+ *  beside the shipped `.git`, or the image starts with tracked deletions. `.cache` is generic hygiene
  *  (a baked project's own build cache), not a fastagent directory.
  *  `.git` is deliberately SHIPPED: the deployed agent's write-back (pull/commit/push) needs the
  *  repo's history+remote — the WYSIWYG bake's freshness/durability loop runs through git, driven by
@@ -145,12 +147,13 @@ const dockerignore = (input) => DOCKERIGNORE_BASE +
         .join("");
 const DOCKERIGNORE_BASE = `${GENERATED_DOCKERIGNORE_MARKER}. Delete this line to take ownership (deploy then keeps your file).
 **/node_modules
-**/${SECRETS_DIRNAME}
+**/${SECRETS_DIRNAME}/**
 **/${STATE_DIRNAME}
 **/.cache
 **/.env
 **/.env.*
 !**/.env.example
+!**/${SECRETS_DIRNAME}/.gitignore
 **/*.log
 # .git is deliberately shipped: the agent can pull to freshen content and push its work back
 # (the generated image installs the git binary when this directory ships a .git; otherwise

package/dist/engines/pi/config.d.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import { type AnyModel } from "./harness.ts";
+import type { AnyModel } from "./harness.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;

package/dist/engines/pi/config.js

@@ -20,7 +20,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { THINKING_LEVELS } from "./harness.js";
+import { THINKING_LEVELS } from "./session-settings.js";
 import { isBindAddress } from "../../bind.js";
 import { moduleLoadHint } from "../../loader.js";
 import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";

package/dist/engines/pi/create.d.ts

@@ -3,7 +3,7 @@ import type { Models, Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
-import { piHarnessFactory } from "./harness.ts";
+import { type AnyModel, piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
@@ -64,6 +64,11 @@ type OnAssembly = (parts: {
     models: Models;
     harnessFactory: ReturnType<typeof piHarnessFactory>;
     lease: Lease;
+    /** The resolved configured pair — what a session without overrides runs on. */
+    defaults: {
+        model: AnyModel;
+        thinkingLevel: ThinkingLevel;
+    };
 }) => void;
 /** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
 export interface CreatePiAgentOptions {

package/dist/engines/pi/create.js

@@ -17,9 +17,9 @@ import { readImageProcessor } from "./read-image.js";
 import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
-import { piHarnessFactory } from "./harness.js";
+import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
-import { reportDefinitionWarnings } from "./report.js";
+import { reportFindingsIfChanged } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
@@ -169,18 +169,24 @@ function buildPiAgent(opts) {
     // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
     // the SAME lease instance the agent runs under — boundary mutations must contend on it.
     const lease = opts.lease ?? inProcessLease();
+    // The assembly's configured PAIR — handed to the factory and to the control plane as ONE value, so
+    // there is no wiring in which they could disagree (which levels exist depends on the model).
+    const defaults = {
+        model: resolveModel(models, opts.model),
+        thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+    };
     const harnessFactory = piHarnessFactory({
         sessions: opts.sessions ?? inMemorySessionStore(),
         env,
         models,
-        model: resolveModel(models, opts.model),
+        model: defaults.model,
         thinkingLevel: opts.thinkingLevel,
         systemPrompt: opts.systemPrompt,
         tools: opts.tools,
         skills: opts.skills,
         live: opts.live,
     });
-    opts.onAssembly?.({ models, harnessFactory, lease });
+    opts.onAssembly?.({ models, harnessFactory, lease, defaults });
     return createPiAgentFromHarness({ lease, observer: opts.observer, cwd: env.cwd, harnessFactory });
 }
 /**
@@ -215,12 +221,6 @@ export function createPiAgent(options) {
         observer: options.observer,
     });
 }
-/** Stable identity of a definition's non-fatal findings, for change-detection in `live` (dedup only). */
-function findingsSignature(def) {
-    const collisions = def.collisions.map((c) => `c:${c.name}:${c.winnerPath}:${c.loserPath}`);
-    const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
-    return [...collisions, ...diagnostics].sort().join("\n");
-}
 /**
  * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
  * call. Returns the definition so callers can surface diagnostics/collisions.
@@ -233,10 +233,11 @@ export async function createPiAgentFromDefinition(dir, options) {
     // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to
     // report (skills/diagnostics/collisions). Serving does NOT close over it — see `live` below.
     const definition = await loadAgentDefinition(dir, { cwd: env.cwd, env });
-    // Findings the caller already reported at boot; `live` re-reports only when the set CHANGES — a
-    // runtime-written bad skill surfaces the moment it appears, while a static finding does not spam
-    // every turn's log. A log-dedup memo, not session state (stateless invoke holds).
-    let reportedFindings = findingsSignature(definition);
+    // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by
+    // the resolved dir): announced once here, and re-announced by a turn or by the control plane's
+    // command list only when the set CHANGES — a runtime-written bad skill surfaces the moment it
+    // appears, a static one does not spam. Log dedup, not session state (stateless invoke holds).
+    reportFindingsIfChanged(definition.dir, definition);
     // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
     // it; a caller's own search_tools wins).
     const tools = withSearchTool(options.tools ?? piDefaultTools());
@@ -259,11 +260,7 @@ export async function createPiAgentFromDefinition(dir, options) {
         // next good edit heals both.
         live: async () => {
             const def = await loadAgentDefinition(dir, { cwd: env.cwd, env });
-            const sig = findingsSignature(def);
-            if (sig !== reportedFindings) {
-                reportedFindings = sig;
-                reportDefinitionWarnings(def.collisions, def.diagnostics);
-            }
+            reportFindingsIfChanged(def.dir, def);
             return {
                 systemPrompt: assembleSystemPrompt({
                     // Segment ①: an authored persona (persona.md, def.persona) overrides the engine identity,

package/dist/engines/pi/definition.d.ts

@@ -41,6 +41,21 @@ export interface LoadAgentDefinitionOptions {
 }
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
+/**
+ * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same
+ * loader, same containment guard, same first-wins collision rule) — for readers that need only the
+ * names and must not pay the full load's ② context walk (every AGENTS.md from cwd to root) for them.
+ * The control plane's `commands()` is that reader, called when a composer opens its completion list.
+ */
+export declare function loadAgentSkills(agentDir: string, options?: {
+    cwd?: string;
+    env?: ExecutionEnv;
+}): Promise<{
+    skills: Skill[];
+    diagnostics: SkillDiagnostic[];
+    collisions: SkillCollision[];
+    dir: string;
+}>;
 /**
  * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
  * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the

package/dist/engines/pi/definition.js

@@ -42,6 +42,11 @@ export async function loadAgentDefinition(agentDir, options = {}) {
         throw new Error(`cannot read ${personaPath}: ${personaRead.error.message}`);
     }
     const persona = personaRead.ok ? personaRead.value : undefined;
+    const { skills, diagnostics, collisions } = await readSkills(e, root);
+    return { contextFiles, persona, skills, diagnostics, collisions, dir: root };
+}
+/** The skills half, shared by the full load and {@link loadAgentSkills}. `root` is already resolved. */
+async function readSkills(e, root) {
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
     // definition loads the same skills on every machine — and, like tools/channels/schedules, a symlink
     // that escapes the agent dir is refused rather than followed (the fourth of four surfaces).
@@ -58,7 +63,23 @@ export async function loadAgentDefinition(agentDir, options = {}) {
             byName.set(skill.name, skill);
         }
     }
-    return { contextFiles, persona, skills: [...byName.values()], diagnostics, collisions, dir: root };
+    return { skills: [...byName.values()], diagnostics, collisions };
+}
+/**
+ * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same
+ * loader, same containment guard, same first-wins collision rule) — for readers that need only the
+ * names and must not pay the full load's ② context walk (every AGENTS.md from cwd to root) for them.
+ * The control plane's `commands()` is that reader, called when a composer opens its completion list.
+ */
+export async function loadAgentSkills(agentDir, options = {}) {
+    const cwd = options.cwd ?? agentDir;
+    const e = options.env ?? new NodeExecutionEnv({ cwd });
+    const rootResult = await e.absolutePath(agentDir);
+    if (!rootResult.ok)
+        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
+    // `dir` is the RESOLVED root, like {@link LoadedDefinition.dir}: readers key per-definition state
+    // (the findings memo) on it, and "./agent" vs an absolute path must not become two definitions.
+    return { ...(await readSkills(e, rootResult.value)), dir: rootResult.value };
 }
 /**
  * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move

package/dist/engines/pi/harness.d.ts

@@ -9,8 +9,9 @@
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import type { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
-import type { PiSessionStore } from "./sessions.ts";
+import { type PiSessionStore } from "./sessions.ts";
 import { type MountedTool } from "./tool.ts";
+import { type OverrideEntryLike } from "./session-settings.ts";
 /**
  * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
  * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
@@ -84,36 +85,19 @@ export declare const SUMMARIZATION_RETRY_POLICY: {
     readonly maxRetries: 3;
     readonly baseDelayMs: 2000;
 };
-export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
-/** The shape both override consumers walk — a session entry, structurally. */
-export interface OverrideEntryLike {
-    type: string;
-    provider?: string;
-    modelId?: string;
-    thinkingLevel?: string;
-}
 /**
- * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
- * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
- * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
- * skipped over to an earlier record: the reporting surface and the execution surface must agree on
- * which record is "the" override.
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
+ * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
+ * here means an upstream default change in either place cannot silently alter deployments. Models
+ * that don't support a level are clamped by pi per model.
  */
-export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
-    model?: {
-        provider: string;
-        modelId: string;
-    };
-    thinkingLevel?: string;
-};
+export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
 /**
- * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
- * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
- * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
- * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
- * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
- * back to the default with a deduped warn (fail visibly without bricking the session — the
- * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
+ * being executable with no control-plane command involved (pi appends these entries itself; a
+ * deployment's configured model can change between restarts). Deduped per session+cause — it would
+ * otherwise repeat every turn.
  */
 export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
     model: AnyModel;

package/dist/engines/pi/harness.js

@@ -8,7 +8,9 @@
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import { log } from "../../log.js";
+import { activePathEntries } from "./sessions.js";
 import { isDeferredTool } from "./tool.js";
+import { resolveSessionSettings } from "./session-settings.js";
 /**
  * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
  * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
@@ -48,7 +50,7 @@ export const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDe
  * here means an upstream default change in either place cannot silently alter deployments. Models
  * that don't support a level are clamped by pi per model.
  */
-const DEFAULT_THINKING_LEVEL = "medium";
+export const DEFAULT_THINKING_LEVEL = "medium";
 /**
  * Resolve the active-tool set for a fresh harness — the ONE place both fallbacks live. pi's harness
  * WRITES active-tool changes to the session (`setActiveTools` → `active_tools_change`) but its
@@ -72,83 +74,30 @@ const DEFAULT_THINKING_LEVEL = "medium";
  * (like L2's findings memo), not session state — the resolve stays derived from the session.
  */
 const warnedRestores = new Set();
-/** pi's ThinkingLevel scale as a checkable set — THE single source for fastagent (session entries
- *  store plain strings; session-control's dispatch validation and capabilities derive from this).
- *  The `satisfies Record<ThinkingLevel, …>` anchor makes it EXHAUSTIVE against pi's union: pi
- *  adding a level turns this into a type error instead of a silent drift where `set_thinking`
- *  rejects a value pi supports. */
-const ALL_THINKING_LEVELS = {
-    off: true,
-    minimal: true,
-    low: true,
-    medium: true,
-    high: true,
-    xhigh: true,
-    max: true,
-};
-export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
 /**
- * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
- * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
- * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
- * skipped over to an earlier record: the reporting surface and the execution surface must agree on
- * which record is "the" override.
- */
-export function lastOverrideEntries(entries) {
-    let model;
-    let modelSeen = false;
-    let thinkingLevel;
-    let thinkingSeen = false;
-    for (let i = entries.length - 1; i >= 0 && !(modelSeen && thinkingSeen); i--) {
-        const e = entries[i];
-        if (!modelSeen && e?.type === "model_change") {
-            modelSeen = true;
-            if (e.provider !== undefined && e.modelId !== undefined)
-                model = { provider: e.provider, modelId: e.modelId };
-        }
-        if (!thinkingSeen && e?.type === "thinking_level_change") {
-            thinkingSeen = true;
-            if (e.thinkingLevel !== undefined)
-                thinkingLevel = e.thinkingLevel;
-        }
-    }
-    return { model, thinkingLevel };
-}
-/**
- * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
- * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
- * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
- * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
- * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
- * back to the default with a deduped warn (fail visibly without bricking the session — the
- * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
+ * being executable with no control-plane command involved (pi appends these entries itself; a
+ * deployment's configured model can change between restarts). Deduped per session+cause — it would
+ * otherwise repeat every turn.
  */
 export function resolveHarnessOverrides(entries, models, defaults, sessionId) {
-    let model = defaults.model;
-    let thinkingLevel = defaults.thinkingLevel;
+    const settings = resolveSessionSettings(entries, models, defaults);
     const warnOnce = (key, message) => {
         const emit = warnedRestores.has(key) ? log.debug : log.warn;
         warnedRestores.add(key);
         emit(message);
     };
-    const recorded = lastOverrideEntries(entries);
-    if (recorded.model) {
-        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
-        if (found)
-            model = found;
-        else {
-            warnOnce(`${sessionId}\u0000model\u0000${recorded.model.provider}/${recorded.model.modelId}`, `[fastagent] session ${sessionId}: recorded model override ${recorded.model.provider}/${recorded.model.modelId} is not in this deployment's registry — using the configured default`);
-        }
+    const dropped = settings.dropped;
+    if (dropped?.model) {
+        warnOnce(`${sessionId}\u0000model\u0000${dropped.model}`, `[fastagent] session ${sessionId}: recorded model override ${dropped.model} is not in this deployment's registry — using the configured default`);
     }
-    if (recorded.thinkingLevel !== undefined) {
-        if (THINKING_LEVELS.has(recorded.thinkingLevel)) {
-            thinkingLevel = recorded.thinkingLevel;
-        }
-        else {
-            warnOnce(`${sessionId}\u0000thinking\u0000${recorded.thinkingLevel}`, `[fastagent] session ${sessionId}: recorded thinking level "${recorded.thinkingLevel}" is unknown — using the configured default`);
-        }
+    if (dropped?.thinkingLevel) {
+        const { recorded, running, known } = dropped.thinkingLevel;
+        warnOnce(`${sessionId}\u0000thinking\u0000${settings.model.provider}/${settings.model.id}\u0000${recorded}`, known
+            ? `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is not supported by ${settings.model.provider}/${settings.model.id} — running at "${running}"`
+            : `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is unknown — using the configured default`);
     }
-    return { model, thinkingLevel };
+    return { model: settings.model, thinkingLevel: settings.thinkingLevel };
 }
 export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     const anyDeferred = tools.some(isDeferredTool);
@@ -170,9 +119,10 @@ export function piHarnessFactory(options) {
     return async (sessionId) => {
         const session = await options.sessions.openOrCreate(sessionId);
         // One extra entry walk per invoke to collect the activation deltas — negligible against the model
-        // call, same trade as L2's per-invoke definition re-read. Serving sessions never branch, so a flat
-        // getEntries() read (no leaf-path walk) is correct.
-        const entries = await session.getEntries();
+        // call, same trade as L2's per-invoke definition re-read. The walk is over the ACTIVE PATH, not
+        // the flat journal: `navigate` moves the leaf, so the tree can hold an abandoned branch whose
+        // activations and overrides this session has left behind.
+        const entries = await activePathEntries(session);
         const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
             ? (e.data?.names ?? [])
             : []);

package/dist/engines/pi/open.d.ts

@@ -4,7 +4,7 @@ import type { SessionControl } from "../../session.ts";
 import type { SessionObserver } from "./invoke.ts";
 import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import type { LoadedDefinition } from "./definition.ts";
+import { type LoadedDefinition } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
 import type { MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {

package/dist/engines/pi/open.js

@@ -14,6 +14,8 @@ import { resolveStateRoot, resolvePlacement } from "../../paths.js";
 import { createPiAgentFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
+import { loadAgentSkills } from "./definition.js";
+import { reportFindingsIfChanged } from "./report.js";
 import { jsonlSessionStore } from "./sessions.js";
 export async function resolveAgentAssembly(dir, options = {}) {
     // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
@@ -73,6 +75,23 @@ export async function createPiAgentFromDir(dir, options = {}) {
         ? createPiSessionControl({
             sessions,
             boundary: () => boundaryParts,
+            // Skills ARE the names a client offers — the resolved set, after collisions were decided
+            // first-wins, which a client cannot reconstruct from the directory. Read LIVE (the directory
+            // is the agent: a skill added while serving is in play on the next turn, so it must be
+            // listable now) and SKILLS-ONLY: this is called when a composer opens its completion list,
+            // and the full load's ② context walk buys nothing here.
+            commands: async () => {
+                const loaded = await loadAgentSkills(agentDir, { cwd: workspace });
+                // A skill whose frontmatter broke simply is not in `skills` — it would disappear from the
+                // author's composer with no signal anywhere. The memo is SHARED with the turn path (keyed
+                // by dir), so a finding is warned when it appears, not once per reader that notices it.
+                reportFindingsIfChanged(loaded.dir, loaded);
+                return loaded.skills.map((skill) => ({
+                    name: skill.name,
+                    description: skill.description,
+                    source: "skill",
+                }));
+            },
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
             // and never cross the data plane's observer seam — without this, an audit tap wired here
             // would miss exactly the mutations it most needs to see (set_model).
@@ -102,6 +121,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
                     lease: parts.lease,
                     models: parts.models,
                     harnessFactory: parts.harnessFactory,
+                    defaults: parts.defaults,
                 };
             }
             : undefined,

package/dist/engines/pi/report.d.ts

@@ -6,8 +6,24 @@ import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
 import type { SkillCollision } from "./definition.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import type { ToolCollision } from "./tool.ts";
+type Findings = {
+    collisions: SkillCollision[];
+    diagnostics: SkillDiagnostic[];
+};
+/**
+ * THE door for definition findings: warns only when this dir's set CHANGED since the last report.
+ * Every reader calls it — boot, the per-turn live read, the control plane's command list — so a
+ * finding is announced when it appears and never repeated. There is deliberately no "record without
+ * printing" variant: a memo entry that trusts some other caller to have printed would silently
+ * swallow findings for a caller that does not.
+ *
+ * `dir` must be the RESOLVED definition root (`LoadedDefinition.dir`), or two spellings of one path
+ * become two memos and warn twice.
+ */
+export declare function reportFindingsIfChanged(dir: string, def: Findings): void;
 export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;
 /** Report per-file module failures. The caller decides whether they are degradations (tools/schedules)
  *  or fatal (declared channels on the serving path). */
 export declare function reportModuleLoadFailures(failures: ModuleLoadFailure[]): void;
+export {};