@pikku/core 0.12.100 → 0.12.102

package/CHANGELOG.md

@@ -1,3 +1,54 @@
+## 0.12.102
+
+### Patch Changes
+
+- f4e2e89: Add file attachments to `EmailService`.
+
+  `BaseSendEmailInput` gains an optional `attachments: EmailAttachment[]`, so it is
+  available on all three input variants — text, HTML and template. The new
+  `EmailAttachment` type is exported from `@pikku/core/services` alongside the
+  input types, and is shaped so that mapping it onto Resend, SendGrid, Nodemailer
+  or SES v2 is a straight field rename rather than a translation.
+
+  `content` is `Uint8Array | string`, where a string is always read as base64.
+  Both forms are accepted because both are what callers already hold: bytes come
+  out of a fetch or a file read, and base64 comes out of a database column or a
+  provider API. `Buffer` is deliberately absent from the type — it is a subclass
+  of `Uint8Array`, so Node callers can still pass one, while the type stays usable
+  in Cloudflare Workers, where `Buffer` does not exist.
+
+  `LocalEmailService` now logs attachment metadata — filename, content type,
+  content id, disposition and content length — instead of dropping the field
+  silently. The content itself is deliberately not logged.
+
+  The template-rendering wrapper documented in the emails skill rebuilt its
+  delegate payload field by field and therefore dropped `attachments`; it now
+  forwards them.
+
+## 0.12.101
+
+### Patch Changes
+
+- e92e30b: Print a CLI failure as its message, not as a JS stack trace.
+
+  Every error that reached the top of `executeCLI` was logged with `console.error('Error:', error)`, which node renders as the full stack — and prefixed it a second time, so a refusal read `Error: Error: Persona 'guest' missing guest…` above ten frames of pikku internals. A `PikkuFetchError` was worse: node inspects an error's own properties, so the whole `Response` came out with it, headers and body stream included, to say `502`.
+
+  An expected failure — a `PikkuError`, or anything carrying `expected: true` — now prints its message alone, and a fetch failure prints `502 Bad Gateway from <url>` without touching the response. Anything else keeps its stack, because a `TypeError` with its frames removed is undiagnosable. `--verbose`/`-v`, or `PIKKU_DEBUG=1` where the flag cannot be typed, adds the stack back to an expected failure.
+
+  The refusals behind the examples — a persona whose roles have drifted, a sign-in the stage rejected — are raised as `PikkuError` so they are classed as deliberate.
+
+- 781797c: Drive a persona's agent turn over the SSE route. The plain `POST /rpc/agent/:name` buffers the entire run before sending a byte, so any run longer than undici's 300s headers timeout failed with `UND_ERR_HEADERS_TIMEOUT` — which is most conversational agents.
+- ccab6ed: Verify a persona's roles against the app's own `getMyScopes` RPC before better-auth's `user.role`. In an app that authorizes on scopes that column is a projection — kept in step for better-auth's own admin endpoints, and absent entirely from an app that declares no such field — so a persona holding exactly what it should was refused for "roles drifted". Configurable via `rolesRpc`; `false` reads better-auth only.
+- 4d0a548: Provision the declared personas from the fabric plugin instead of the server lifecycle.
+
+  `provisionPersonas` was documented as a call an app makes from `pikkuServerLifecycle`'s `afterStart`. That hook is invoked by `pikku serve` and `pikku dev` and by nothing else — no deploy runtime calls it — so on any stage deployed to Workers or a serverless target the provisioning never ran, and every persona signed in holding no roles.
+
+  `pikkuFabric` now takes `personas`. The operator endpoint resolves the address the caller wants to act as; a miss provisions the declaration and looks again. On a stage that already holds the persona that is one query, and the pass only runs when there is genuinely something absent to create.
+
+  Sign-in no longer creates accounts of its own. `OperatorSignInOptions.createMissing` and `PIKKU_PERSONA_CREATE_MISSING` are gone, and an address no declaration claims stays a 404 however many times it is asked for. `provisionPersonas` is no longer exported — the plugin is the only caller.
+
+  `pikku persona sync <environment>` is unchanged: it still reports who an environment will provision and why anyone was skipped, and still writes nothing.
+
 ## 0.12.100
 
 ### Patch Changes

package/dist/services/email-service.d.ts

@@ -4,6 +4,18 @@ export interface EmailTemplateReference {
     locale?: string;
     data?: Record<string, unknown>;
 }
+export interface EmailAttachment {
+    filename: string;
+    /**
+     * Raw bytes, or the content already base64-encoded. A `string` is always
+     * read as base64 — never as a plain-text body — so text attachments must be
+     * encoded by the caller.
+     */
+    content: Uint8Array | string;
+    contentType?: string;
+    contentId?: string;
+    disposition?: 'attachment' | 'inline';
+}
 export interface BaseSendEmailInput {
     to: string | string[];
     from?: string;
@@ -12,6 +24,7 @@ export interface BaseSendEmailInput {
     replyTo?: string | string[];
     headers?: Record<string, string>;
     subject?: string;
+    attachments?: EmailAttachment[];
 }
 export interface SendTextEmailInput extends BaseSendEmailInput {
     text: string;

package/dist/services/http-personas.d.ts

@@ -49,6 +49,17 @@ export interface HttpPersonasConfig {
     sessionPath?: string;
     /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
     rpcPath?: string;
+    /**
+     * Exposed RPC that reports the CALLER's own roles, as `{ roles: string[] }`.
+     * Default `getMyScopes`. Pass `false` to skip it and read better-auth only.
+     *
+     * Asked before better-auth's `user.role`, because in an app that authorizes
+     * on scopes that column is a projection rather than the model — it exists so
+     * better-auth's own admin endpoints have something to read, is written by
+     * whatever keeps it in step, and is absent entirely from an app that declares
+     * no such field. A persona verified against it is verified against a copy.
+     */
+    rolesRpc?: string | false;
     /**
      * Default model a persona thinks with when `converse(...)` is called without
      * an explicit `model`. Its own turns/approvals/evaluation run in-process via
@@ -86,17 +97,36 @@ export declare class HttpPersona implements ScenarioPersona {
     /**
      * The roles the stage says this session holds.
      *
-     * Read from better-auth's `get-session`, which is what most pikku apps are
-     * running and where its admin plugin puts `role` — on the user, as a
-     * comma-separated list. A target that answers something else returns `null`
-     * rather than an empty list, because "this stage does not report roles" and
-     * "this person has none" call for opposite responses from the caller.
+     * {@link HttpPersonasConfig.rolesRpc} first, then better-auth's
+     * `get-session` — where its admin plugin puts `role` on the user, as a
+     * comma-separated list. A target that answers neither returns `null` rather
+     * than an empty list, because "this stage does not report roles" and "this
+     * person has none" call for opposite responses from the caller.
      */
     sessionRoles(): Promise<string[] | null>;
-    /** Start/continue the target agent's run over HTTP as this persona. */
+    /**
+     * The caller's own roles, from the app's own RPC. `null` for every answer
+     * that is not a role list — an app without the RPC 404s here, which is a
+     * reason to go on and ask better-auth, not a reason to report "none".
+     */
+    private rolesFromRpc;
+    private rolesFromSession;
+    /**
+     * Start/continue the target agent's run over HTTP as this persona.
+     *
+     * The SSE route, not the plain one. `POST /rpc/agent/:name` buffers the whole
+     * run before it sends a single byte, so a run longer than the client's
+     * headers timeout — 300s in undici, which is what Node and Bun both use —
+     * fails with `UND_ERR_HEADERS_TIMEOUT` and no way to tell it apart from a
+     * stage that is down. An agent that talks for several minutes, which is the
+     * normal case for anything conversational, cannot be driven that way at all.
+     * The stream sends its first event immediately and the run's length stops
+     * mattering.
+     */
     private agentRun;
     /** Answer the target agent's pending approvals over HTTP and continue. */
     private agentApprove;
+    private sendAgent;
     private postAgent;
     private postRpc;
     /** Drop the session, so the next call signs in again before it goes out. */

package/dist/services/http-personas.js

@@ -108,16 +108,46 @@ export class HttpPersona {
     /**
      * The roles the stage says this session holds.
      *
-     * Read from better-auth's `get-session`, which is what most pikku apps are
-     * running and where its admin plugin puts `role` — on the user, as a
-     * comma-separated list. A target that answers something else returns `null`
-     * rather than an empty list, because "this stage does not report roles" and
-     * "this person has none" call for opposite responses from the caller.
+     * {@link HttpPersonasConfig.rolesRpc} first, then better-auth's
+     * `get-session` — where its admin plugin puts `role` on the user, as a
+     * comma-separated list. A target that answers neither returns `null` rather
+     * than an empty list, because "this stage does not report roles" and "this
+     * person has none" call for opposite responses from the caller.
      */
     async sessionRoles() {
         if (!this.signedIn) {
             await this.login();
         }
+        const fromRpc = await this.rolesFromRpc();
+        if (fromRpc)
+            return fromRpc;
+        return await this.rolesFromSession();
+    }
+    /**
+     * The caller's own roles, from the app's own RPC. `null` for every answer
+     * that is not a role list — an app without the RPC 404s here, which is a
+     * reason to go on and ask better-auth, not a reason to report "none".
+     */
+    async rolesFromRpc() {
+        const rpcName = this.config.rolesRpc ?? 'getMyScopes';
+        if (rpcName === false)
+            return null;
+        let res;
+        try {
+            res = await this.postRpc(rpcName, {});
+        }
+        catch {
+            return null;
+        }
+        if (!res.ok)
+            return null;
+        const { body } = await readScenarioHttpResponse(res);
+        const roles = body?.roles ?? body?.data?.roles;
+        if (!Array.isArray(roles))
+            return null;
+        return roles.filter((name) => typeof name === 'string');
+    }
+    async rolesFromSession() {
         const mount = authMount(this.config.operator?.signInPath ?? this.config.signInPath);
         const sessionPath = this.config.sessionPath ?? `${mount ?? '/auth'}/get-session`;
         const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
@@ -152,14 +182,25 @@ export class HttpPersona {
         // stage reporting "none", not a stage that cannot report.
         return user ? [] : null;
     }
-    /** Start/continue the target agent's run over HTTP as this persona. */
+    /**
+     * Start/continue the target agent's run over HTTP as this persona.
+     *
+     * The SSE route, not the plain one. `POST /rpc/agent/:name` buffers the whole
+     * run before it sends a single byte, so a run longer than the client's
+     * headers timeout — 300s in undici, which is what Node and Bun both use —
+     * fails with `UND_ERR_HEADERS_TIMEOUT` and no way to tell it apart from a
+     * stage that is down. An agent that talks for several minutes, which is the
+     * normal case for anything conversational, cannot be driven that way at all.
+     * The stream sends its first event immediately and the run's length stops
+     * mattering.
+     */
     async agentRun(agentName, message, threadId, resourceId) {
-        const raw = await this.postAgent(`agent/${agentName}`, {
+        const res = await this.sendAgent(`agent/${agentName}/stream`, {
             message,
             threadId,
             resourceId,
         });
-        return normalizeAgentReply(raw);
+        return await collectAgentStream(res);
     }
     /** Answer the target agent's pending approvals over HTTP and continue. */
     async agentApprove(agentName, runId, decisions) {
@@ -170,7 +211,7 @@ export class HttpPersona {
         return normalizeAgentReply(raw);
     }
     // knowledge: decisions/internals/scenario-agent-calls-sign-in-on-401-only.md
-    async postAgent(subPath, body) {
+    async sendAgent(subPath, body) {
         const rpcPath = this.config.rpcPath ?? '/rpc';
         const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
         const send = () => this.jar.fetch(url, {
@@ -191,6 +232,10 @@ export class HttpPersona {
             const text = (await res.text().catch(() => '')).slice(0, 300);
             throw new Error(`[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`);
         }
+        return res;
+    }
+    async postAgent(subPath, body) {
+        const res = await this.sendAgent(subPath, body);
         if (res.status === 204)
             return undefined;
         const text = await res.text();
@@ -218,6 +263,80 @@ export class HttpPersona {
         this.signedIn = true;
     }
 }
+/**
+ * Reduce the agent's SSE run into the same reply shape the plain route returns.
+ *
+ * `RUN_ERROR` is raised rather than returned: the plain route answers a failed
+ * run with a non-2xx, and a scenario that read an error as an empty transcript
+ * would score the agent on silence it never produced.
+ */
+async function collectAgentStream(res) {
+    const body = res.body;
+    if (!body) {
+        throw new Error('[scenario] the agent stream carried no body');
+    }
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    let buffer = '';
+    let text = '';
+    let runId = '';
+    const pendingApprovals = [];
+    const consume = (line) => {
+        if (!line.startsWith('data:'))
+            return;
+        const payload = line.slice(5).trim();
+        if (!payload)
+            return;
+        let event;
+        try {
+            event = JSON.parse(payload);
+        }
+        catch {
+            return;
+        }
+        if (typeof event.runId === 'string' && event.runId)
+            runId = event.runId;
+        if (event.type === 'TEXT_MESSAGE_CONTENT' &&
+            typeof event.delta === 'string') {
+            text += event.delta;
+        }
+        else if (event.type === 'approval-request') {
+            pendingApprovals.push({
+                toolCallId: String(event.toolCallId),
+                toolName: String(event.toolName),
+                args: event.args,
+                reason: typeof event.reason === 'string' ? event.reason : undefined,
+            });
+        }
+        else if (event.type === 'RUN_ERROR' || event.type === 'error') {
+            const message = event.message ?? event.errorText ?? 'the agent run failed';
+            throw new Error(`[scenario] agent run failed: ${String(message)}`);
+        }
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines)
+                consume(line);
+        }
+        if (buffer)
+            consume(buffer);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return {
+        text,
+        runId,
+        status: pendingApprovals.length > 0 ? 'suspended' : 'completed',
+        pendingApprovals: pendingApprovals.length > 0 ? pendingApprovals : undefined,
+    };
+}
 /** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
 function normalizeAgentReply(raw) {
     const r = (raw ?? {});

package/dist/services/index.d.ts

@@ -20,7 +20,7 @@ export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary,
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
 export type { JWTService } from './jwt-service.js';
-export type { EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
+export type { EmailAttachment, EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { renderEmail, type EmailAssets, type EmailTemplateAssets, type EmailTemplateHashes, type RenderEmailRequest, type RenderedEmailResult, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
 export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';

package/dist/services/local-email-service.js

@@ -20,6 +20,15 @@ export class LocalEmailService {
         if ('text' in input && typeof input.text === 'string') {
             payload.textLength = input.text.length;
         }
+        if (input.attachments?.length) {
+            payload.attachments = input.attachments.map((attachment) => ({
+                filename: attachment.filename,
+                contentType: attachment.contentType ?? null,
+                contentId: attachment.contentId ?? null,
+                disposition: attachment.disposition ?? 'attachment',
+                contentLength: attachment.content.length,
+            }));
+        }
         console.info(JSON.stringify(payload));
         return {};
     }

package/dist/services/persona-sign-in.d.ts

@@ -71,16 +71,6 @@ export interface OperatorSignInOptions {
      * the function: tokens expire, and a long run re-logs-in after a 401.
      */
     token: string | (() => string | Promise<string>);
-    /**
-     * Create the persona's user row when the target has no account for that
-     * address.
-     *
-     * Off by default, which is the whole point of the deployed path: a persona is
-     * meant to be a real account somebody provisioned, and a test run that
-     * silently writes users into a live database is a side effect nobody asked
-     * for. Turn it on for throwaway stages.
-     */
-    createMissing?: boolean;
     /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
     signInPath?: string;
 }

package/dist/services/persona-sign-in.js

@@ -1,4 +1,5 @@
 import { deriveActorSecret } from './persona-actor-secret.js';
+import { PikkuError } from '../errors/error-handler.js';
 /**
  * The header `resolveImpersonatedSession` reads the target user id from.
  *
@@ -7,9 +8,15 @@ import { deriveActorSecret } from './persona-actor-secret.js';
  * it back. The two agree by protocol, the way an HTTP header always does.
  */
 export const IMPERSONATE_USER_ID_HEADER = 'x-pikku-impersonate-user-id';
+/**
+ * A sign-in the target refused. `PikkuError`, not `Error`, so the CLI prints
+ * this message alone: an expired token or a persona the stage has never seen is
+ * something to go and fix, and a stack trace through the fetch internals only
+ * buries the status and the body that say which one it is.
+ */
 const failed = async (what, personaId, res) => {
     const body = (await res.text().catch(() => '')).slice(0, 300);
-    return new Error(`[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`);
+    return new PikkuError(`[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`);
 };
 /**
  * Sign a persona in through the Better Auth actor plugin — the local-development
@@ -93,12 +100,7 @@ export const establishOperatorSession = async (fetchImpl, apiUrl, persona, optio
         headers: { 'content-type': 'application/json', ...extraHeaders },
         body: JSON.stringify({
             token,
-            actAs: {
-                email: persona.email,
-                name: persona.name,
-                create: options.createMissing ?? false,
-                ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
-            },
+            actAs: { email: persona.email },
         }),
     });
     if (!res.ok) {
@@ -106,12 +108,12 @@ export const establishOperatorSession = async (fetchImpl, apiUrl, persona, optio
     }
     const setCookies = res.headers.getSetCookie?.() ?? [];
     if (setCookies.length === 0) {
-        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
+        throw new PikkuError(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
     }
     const body = (await res.json().catch(() => null));
     const userId = body?.actAs?.userId;
     if (!userId) {
-        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
+        throw new PikkuError(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
             'the target is running a @pikku/better-auth too old to resolve one');
     }
     return { setCookies, userId: String(userId) };

package/dist/wirings/cli/cli-runner.js

@@ -1,11 +1,11 @@
 import { NotFoundError } from '../../errors/errors.js';
-import { isExpectedError } from '../../errors/error-handler.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { unsupportedChannelRemote } from '../channel/channel-rpc.types.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { LocalVariablesService } from '../../services/local-variables.js';
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js';
+import { formatCLIError, wantsStackTrace } from './format-cli-error.js';
 /** The caller is expected to catch this and call `process.exit(exitCode)`. */
 export class CLIError extends Error {
     exitCode;
@@ -323,16 +323,7 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         if (error instanceof CLIError) {
             throw error;
         }
-        // An expected PikkuError's message is written to be the whole output.
-        if (isExpectedError(error)) {
-            console.error(error.message);
-        }
-        else {
-            console.error('Error:', error);
-        }
-        if (args.includes('--verbose') || args.includes('-v')) {
-            console.error('Stack trace:', error.stack);
-        }
+        console.error(formatCLIError(error, { verbose: wantsStackTrace(args) }));
         throw new CLIError(error.message || String(error), 1);
     }
 }

package/dist/wirings/cli/format-cli-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The user asked to see the machinery. `--verbose`/`-v` is the flag the CLI
+ * already documents; `PIKKU_DEBUG` is for the times the flag cannot be typed —
+ * a command that does not declare the option, or a CLI run from a script.
+ */
+export declare const wantsStackTrace: (args: string[], env?: Record<string, string | undefined>) => boolean;
+/**
+ * What the CLI prints when a command throws.
+ *
+ * A stack trace is an answer to "which line of pikku broke", and almost every
+ * failure a user actually hits is not that question: a missing role, an expired
+ * token, a gateway that is down. Those errors are written to be read, so the
+ * message alone is the whole output — an expected error is one deliberately
+ * raised as `PikkuError` (or carrying `expected: true`), and everything else
+ * keeps its stack, because an unexpected `TypeError` with its frames removed is
+ * a bug nobody can diagnose.
+ *
+ * A stack already begins with `Name: message`, so it is returned as-is: the
+ * `console.error('Error:', error)` this replaced produced the doubled
+ * `Error: Error: …` prefix that made even real traces look broken.
+ */
+export declare const formatCLIError: (error: unknown, { verbose }?: {
+    verbose?: boolean;
+}) => string;

package/dist/wirings/cli/format-cli-error.js

@@ -0,0 +1,68 @@
+import { isExpectedError } from '../../errors/error-handler.js';
+const isFetchFailure = (error) => {
+    const candidate = error;
+    return (typeof candidate?.status === 'number' &&
+        typeof candidate?.statusText === 'string' &&
+        typeof candidate?.response === 'object' &&
+        candidate.response !== null);
+};
+/**
+ * The user asked to see the machinery. `--verbose`/`-v` is the flag the CLI
+ * already documents; `PIKKU_DEBUG` is for the times the flag cannot be typed —
+ * a command that does not declare the option, or a CLI run from a script.
+ */
+export const wantsStackTrace = (args, env = process.env) => args.includes('--verbose') ||
+    args.includes('-v') ||
+    (env.PIKKU_DEBUG !== undefined &&
+        env.PIKKU_DEBUG !== '' &&
+        env.PIKKU_DEBUG !== '0');
+/**
+ * What the CLI prints when a command throws.
+ *
+ * A stack trace is an answer to "which line of pikku broke", and almost every
+ * failure a user actually hits is not that question: a missing role, an expired
+ * token, a gateway that is down. Those errors are written to be read, so the
+ * message alone is the whole output — an expected error is one deliberately
+ * raised as `PikkuError` (or carrying `expected: true`), and everything else
+ * keeps its stack, because an unexpected `TypeError` with its frames removed is
+ * a bug nobody can diagnose.
+ *
+ * A stack already begins with `Name: message`, so it is returned as-is: the
+ * `console.error('Error:', error)` this replaced produced the doubled
+ * `Error: Error: …` prefix that made even real traces look broken.
+ */
+export const formatCLIError = (error, { verbose = false } = {}) => {
+    if (isFetchFailure(error)) {
+        return formatFetchFailure(error, verbose);
+    }
+    const stack = error?.stack;
+    const message = error?.message;
+    if (!isExpectedError(error)) {
+        return typeof stack === 'string' && stack ? stack : String(error);
+    }
+    const text = typeof message === 'string' && message ? message : String(error);
+    return verbose && typeof stack === 'string' && stack
+        ? `${text}\n${stack}`
+        : text;
+};
+/**
+ * A failed HTTP call, as the line the user needs: which status, from which URL.
+ *
+ * Never the `Response` itself. Node inspects an error's own properties when it
+ * prints one, so a thrown fetch error used to dump the headers, the body stream
+ * and the redirect flags — pages of output whose only real content was the
+ * status code.
+ */
+const formatFetchFailure = (error, verbose) => {
+    const url = error.response?.url;
+    const where = url ? ` from ${url}` : '';
+    const summary = `${error.status} ${error.statusText}${where}`;
+    const message = error.message;
+    const text = message && message !== error.statusText
+        ? `${message}\n  ${summary}`
+        : summary;
+    const stack = error.stack;
+    return verbose && typeof stack === 'string' && stack
+        ? `${text}\n${stack}`
+        : text;
+};

package/dist/wirings/virtual-user/virtual-user-scaffold.d.ts

@@ -57,7 +57,6 @@ export declare const VIRTUAL_USER_VARIABLES: {
      * fallback for a run nobody handed a token to, which is what a schedule is.
      */
     readonly operatorToken: "FABRIC_OPERATOR_TOKEN";
-    readonly createMissing: "PIKKU_PERSONA_CREATE_MISSING";
 };
 /**
  * Which door under the auth mount, given the credential in hand.

package/dist/wirings/virtual-user/virtual-user-scaffold.js

@@ -34,7 +34,6 @@ export const VIRTUAL_USER_VARIABLES = {
      * fallback for a run nobody handed a token to, which is what a schedule is.
      */
     operatorToken: 'FABRIC_OPERATOR_TOKEN',
-    createMissing: 'PIKKU_PERSONA_CREATE_MISSING',
 };
 /**
  * Which door under the auth mount, given the credential in hand.
@@ -330,8 +329,6 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
             throw new Error(`Neither an operator token nor ${VIRTUAL_USER_VARIABLES.secret} is available — there is nobody for the virtual user to be. ` +
                 `Hand a Fabric operator token in with the run against a deployed stage, or export ${VIRTUAL_USER_VARIABLES.secret} against a local \`pikku dev\` target.`);
         }
-        const createMissing = String(await variables.get(VIRTUAL_USER_VARIABLES.createMissing)) ===
-            'true';
         const model = await variables.get(VIRTUAL_USER_VARIABLES.model);
         if (!model) {
             throw new Error(`${VIRTUAL_USER_VARIABLES.model} is not set — no model to think with.`);
@@ -362,7 +359,6 @@ export const executeVirtualUserRun = async ({ runStore, metaService, agentRunner
                 ? {
                     operator: {
                         token,
-                        createMissing,
                         signInPath: signInPathFor(configuredSignInPath, 'fabric'),
                     },
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.100",
+  "version": "0.12.102",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -39,6 +39,11 @@ const skipped = new Set([
   'build',
   '.git',
   'coverage',
+  // Agent scratch worktrees are whole Pikku projects generated by whatever CLI
+  // version happened to scaffold them, so discovery finds them and reports a
+  // barrel this repo does not own. They are gitignored and belong to no
+  // workspace, which is what makes them out of scope rather than merely noisy.
+  '.claude',
 ])
 
 const findProjects = (dir: string, out: string[] = []): string[] => {

package/src/no-root-barrel.test.ts

@@ -22,11 +22,19 @@ const skipDirectory = new Set([
   '.git',
   'build',
   'coverage',
+  // Agent scratch worktrees are whole Pikku projects scaffolded by whatever CLI
+  // version happened to write them, so they carry specifiers this repo does not
+  // own. They are gitignored and belong to no workspace, which is what puts them
+  // out of scope rather than merely making them noisy.
+  '.claude',
 ])
 
+/** A verifier's scratch project, left behind by a run that did not clean up. */
+const isScratchProject = (entry: string) => entry.startsWith('.tmp-')
+
 const walk = (dir: string, out: string[] = []): string[] => {
   for (const entry of readdirSync(dir)) {
-    if (skipDirectory.has(entry)) continue
+    if (skipDirectory.has(entry) || isScratchProject(entry)) continue
     const path = join(dir, entry)
     if (statSync(path).isDirectory()) walk(path, out)
     else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)