@pikku/cli 0.12.137 → 0.12.143

package/dist/src/fabric/lib/git.js

@@ -41,11 +41,11 @@ function envWithoutInheritedRepo() {
     }
     return env;
 }
-function git(args, cwd = process.cwd()) {
+function git(args, cwd = process.cwd(), extraEnv) {
     return new Promise((resolve, reject) => {
         const child = spawn('git', args, {
             cwd,
-            env: envWithoutInheritedRepo(),
+            env: { ...envWithoutInheritedRepo(), ...extraEnv },
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         let stdout = '';
@@ -218,3 +218,71 @@ export async function isGitRepo(cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * Does this repository have the given remote?
+ *
+ * Separate from `getRemoteUrl` throwing, because "no origin" is an ordinary
+ * state that `link` acts on rather than an error it reports: a developer who
+ * has not pushed anywhere yet is exactly who repo provisioning is for.
+ */
+export async function hasRemote(remote = 'origin', cwd) {
+    try {
+        await git(['remote', 'get-url', remote], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Does HEAD resolve? False in a repository with no commits yet. */
+export async function hasCommits(cwd) {
+    try {
+        await git(['rev-parse', '--verify', 'HEAD'], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function addRemote(name, url, cwd) {
+    await git(['remote', 'add', name, url], cwd);
+}
+export async function removeRemote(name, cwd) {
+    try {
+        await git(['remote', 'remove', name], cwd);
+    }
+    catch {
+        /* best-effort: only used to undo a remote we just added */
+    }
+}
+/**
+ * Push `branch` to `remote` and set it as upstream, authenticating with a
+ * one-shot credential.
+ *
+ * The credential is passed through the ENVIRONMENT and read back by an inline
+ * credential helper, rather than embedded in the remote URL. Both a URL like
+ * `https://user:token@host/...` and `-c http.<url>.extraheader=...` put the
+ * secret in the process's argv, where any other user on the machine can read it
+ * out of `ps`. This way argv holds only the shape of the helper, and the token
+ * never reaches `.git/config` either — so it cannot outlive the push.
+ */
+export async function pushWithCredential(remote, branch, credential, cwd) {
+    await git([
+        '-c',
+        'credential.helper=',
+        '-c',
+        'credential.helper=!f() { echo "username=$PIKKU_GIT_USERNAME"; echo "password=$PIKKU_GIT_PASSWORD"; }; f',
+        'push',
+        '-u',
+        remote,
+        `HEAD:refs/heads/${branch}`,
+    ], cwd, {
+        PIKKU_GIT_USERNAME: credential.username,
+        PIKKU_GIT_PASSWORD: credential.password,
+        // Any configured interactive helper (osxkeychain, a GUI prompt) would be
+        // consulted first and could hang a CLI with no one at the terminal. The
+        // empty `credential.helper=` above resets the inherited list; this stops
+        // git falling back to a terminal prompt if ours somehow yields nothing.
+        GIT_TERMINAL_PROMPT: '0',
+    });
+}

package/dist/src/functions/commands/db-export.js

@@ -1,7 +1,5 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
 import { pikkuSessionlessFunc } from '#pikku/function';
-import { exportSchema } from '../db/local-db.js';
+import { writeSchemaArtifact } from '../db/local-db.js';
 /**
  * Publish this package's schema so a project consuming it as an addon can
  * create its tables.
@@ -16,15 +14,12 @@ import { exportSchema } from '../db/local-db.js';
 export const dbExport = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config }) => {
-        const artifact = await exportSchema(config.rootDir, config.db?.pgliteExtensions);
-        const dialects = Object.keys(artifact);
+        const { file, dialects } = await writeSchemaArtifact(config.rootDir, config.outDir, config.db?.pgliteExtensions);
         if (dialects.length === 0) {
-            logger.info('db export: no db/sqlite or db/postgres migrations — nothing to publish');
+            logger.info(`db export: no db/sqlite or db/postgres migrations — wrote ${file} empty, ` +
+                'which is how a consumer tells "no tables" from "never published"');
             return;
         }
-        const file = join(config.outDir, 'db', 'pikku-db-meta.gen.json');
-        mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
         logger.info(`db export: wrote ${file} for ${dialects.join(', ')}`);
         logger.info('  Ship it with the package — a consumer resolves it through the package name.');
     },

package/dist/src/functions/commands/dev.js

@@ -159,23 +159,17 @@ export const dev = pikkuSessionlessFunc({
             ? await createKysely(resolvedLocalDb)
             : undefined;
         const resolvedRuntimeDir = config.runtimeDir ?? join(config.rootDir, '.pikku-runtime');
-        const localContentConfig = userConfig.content
-            ? {
-                localFileUploadPath: userConfig.content.contentPath
-                    ? resolve(config.rootDir, userConfig.content.contentPath)
-                    : join(resolvedRuntimeDir, 'content'),
-                uploadUrlPrefix: userConfig.content.uploadUrlPrefix ?? '/upload',
-                assetUrlPrefix: userConfig.content.assetUrlPrefix ?? '/assets',
-                server: `http://${hostname}:${resolvedPort}`,
-                sizeLimit: userConfig.content.sizeLimit,
-            }
-            : undefined;
-        const contentSigningJWT = localContentConfig
-            ? createEphemeralContentSigningJWT()
-            : undefined;
-        const localContent = localContentConfig && contentSigningJWT
-            ? new LocalContent(localContentConfig, logger, contentSigningJWT)
-            : undefined;
+        const localContentConfig = {
+            localFileUploadPath: userConfig.content?.contentPath
+                ? resolve(config.rootDir, userConfig.content.contentPath)
+                : join(resolvedRuntimeDir, 'content'),
+            uploadUrlPrefix: userConfig.content?.uploadUrlPrefix ?? '/upload',
+            assetUrlPrefix: userConfig.content?.assetUrlPrefix ?? '/assets',
+            server: `http://${hostname}:${resolvedPort}`,
+            sizeLimit: userConfig.content?.sizeLimit,
+        };
+        const contentSigningJWT = createEphemeralContentSigningJWT();
+        const localContent = new LocalContent(localContentConfig, logger, contentSigningJWT);
         const schedulerService = new InMemorySchedulerService();
         const agentStorage = kysely
             ? new KyselyAgentStorageService(kysely)
@@ -236,7 +230,7 @@ export const dev = pikkuSessionlessFunc({
             agentRunService,
             eventHub,
             ...(kysely ? { kysely } : {}),
-            ...(localContent ? { content: localContent } : {}),
+            content: localContent,
         };
         const singletonServices = await userCreateSingletonServices(userConfig, {
             ...inMemoryServices,

package/dist/src/functions/commands/enable.d.ts

@@ -5,4 +5,5 @@ export declare const enableAgent: import("#pikku/function").PikkuFunctionConfig<
 export declare const enableWorkflow: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
 export declare const enableEvents: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
 export declare const enableRemoteRpc: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const enableRemoteJobs: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
 export declare const enableWebhook: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/enable.js

@@ -37,6 +37,9 @@ export const enableEvents = pikkuVoidFunc({
 export const enableRemoteRpc = pikkuVoidFunc({
     func: async ({ logger, config }) => enableFeature('remoteRpc', logger, config),
 });
+export const enableRemoteJobs = pikkuVoidFunc({
+    func: async ({ logger, config }) => enableFeature('remoteJobs', logger, config),
+});
 export const enableWebhook = pikkuVoidFunc({
     func: async ({ logger, config }) => enableFeature('webhook', logger, config),
 });

package/dist/src/functions/commands/knowledge-reconcile.d.ts

@@ -0,0 +1,45 @@
+import { renderKnowledgeReconcile } from '../knowledge/render.js';
+export declare const knowledgeReconcile: import("#pikku/function").PikkuFunctionConfig<Record<string, never>, {
+    kind: "hold" | "idle" | "repair-note" | "write-plan" | "ask-user" | "dispatch";
+    reason: string;
+    note?: string | undefined;
+    hold?: string | undefined;
+    notes?: string[] | undefined;
+    question?: {
+        header: string;
+        question: string;
+        options: {
+            label: string;
+            description?: string | undefined;
+        }[];
+    } | undefined;
+}, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<Record<string, never>, {
+    kind: "hold" | "idle" | "repair-note" | "write-plan" | "ask-user" | "dispatch";
+    reason: string;
+    note?: string | undefined;
+    hold?: string | undefined;
+    notes?: string[] | undefined;
+    question?: {
+        header: string;
+        question: string;
+        options: {
+            label: string;
+            description?: string | undefined;
+        }[];
+    } | undefined;
+}, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<Record<string, never>, {
+    kind: "hold" | "idle" | "repair-note" | "write-plan" | "ask-user" | "dispatch";
+    reason: string;
+    note?: string | undefined;
+    hold?: string | undefined;
+    notes?: string[] | undefined;
+    question?: {
+        header: string;
+        question: string;
+        options: {
+            label: string;
+            description?: string | undefined;
+        }[];
+    } | undefined;
+}, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export { renderKnowledgeReconcile };

package/dist/src/functions/commands/knowledge-reconcile.js

@@ -0,0 +1,11 @@
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { runKnowledgeReconcile } from '@pikku/knowledge';
+import { renderKnowledgeReconcile } from '../knowledge/render.js';
+import { KnowledgeReconcileInputSchema, KnowledgeReconcileOutputSchema, } from '../knowledge/schemas.js';
+export const knowledgeReconcile = pikkuSessionlessFunc({
+    description: 'Say the one thing to do next with the knowledge base — repair a note, write a plan, ask the user, dispatch a build, or nothing — derived from what is on disk rather than from what a previous step remembered to announce.',
+    input: KnowledgeReconcileInputSchema,
+    output: KnowledgeReconcileOutputSchema,
+    func: async ({ config }) => runKnowledgeReconcile(config.rootDir),
+});
+export { renderKnowledgeReconcile };

package/dist/src/functions/commands/serve.js

@@ -62,23 +62,17 @@ export const serve = pikkuSessionlessFunc({
             ? await createKysely(resolvedLocalDb)
             : undefined;
         const resolvedRuntimeDir = config.runtimeDir ?? join(config.rootDir, '.pikku-runtime');
-        const localContentConfig = userConfig.content
-            ? {
-                localFileUploadPath: userConfig.content.contentPath
-                    ? resolve(config.rootDir, userConfig.content.contentPath)
-                    : join(resolvedRuntimeDir, 'content'),
-                uploadUrlPrefix: userConfig.content.uploadUrlPrefix ?? '/upload',
-                assetUrlPrefix: userConfig.content.assetUrlPrefix ?? '/assets',
-                server: `http://${hostname}:${resolvedPort}`,
-                sizeLimit: userConfig.content.sizeLimit,
-            }
-            : undefined;
-        const contentSigningJWT = localContentConfig
-            ? createEphemeralContentSigningJWT()
-            : undefined;
-        const localContent = localContentConfig && contentSigningJWT
-            ? new LocalContent(localContentConfig, logger, contentSigningJWT)
-            : undefined;
+        const localContentConfig = {
+            localFileUploadPath: userConfig.content?.contentPath
+                ? resolve(config.rootDir, userConfig.content.contentPath)
+                : join(resolvedRuntimeDir, 'content'),
+            uploadUrlPrefix: userConfig.content?.uploadUrlPrefix ?? '/upload',
+            assetUrlPrefix: userConfig.content?.assetUrlPrefix ?? '/assets',
+            server: `http://${hostname}:${resolvedPort}`,
+            sizeLimit: userConfig.content?.sizeLimit,
+        };
+        const contentSigningJWT = createEphemeralContentSigningJWT();
+        const localContent = new LocalContent(localContentConfig, logger, contentSigningJWT);
         const schedulerService = new InMemorySchedulerService();
         const agentStorage = kysely
             ? new KyselyAgentStorageService(kysely)
@@ -121,7 +115,7 @@ export const serve = pikkuSessionlessFunc({
             agentRunService,
             eventHub,
             ...(kysely ? { kysely } : {}),
-            ...(localContent ? { content: localContent } : {}),
+            content: localContent,
         };
         const singletonServices = await userCreateSingletonServices(userConfig, {
             ...inMemoryServices,

package/dist/src/functions/db/local-db.d.ts

@@ -74,8 +74,6 @@ export declare function resolveDb(userConfig: UserConfigShape, rootDir: string,
     defaultSchema?: string;
     pgliteExtensions?: string[];
 } | string): ResolvedDb | null;
-/** @deprecated Use resolveDb(userConfig, ...) instead. */
-export declare function resolveLocalDb(sqliteDb: string | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedSqliteDb | null;
 /**
  * What an embedded PGlite instance needs beyond its data directory: where to
  * resolve extension packages from, and which ones to load.
@@ -356,6 +354,18 @@ export interface AddonDeclaration {
  * projects on either engine.
  */
 export declare function exportSchema(rootDir: string, pgliteExtensions?: string[]): Promise<SchemaArtifact>;
+/**
+ * Write the artifact a consumer reads, whether or not this package has tables.
+ *
+ * An addon with no tables still publishes, because the consumer's only other
+ * reading of an absent file is "this package cannot say", which it must treat
+ * as a broken publish. The empty artifact is the addon stating, in a file that
+ * ships, that it needs nothing.
+ */
+export declare function writeSchemaArtifact(rootDir: string, outDir: string, pgliteExtensions?: string[]): Promise<{
+    file: string;
+    dialects: string[];
+}>;
 /**
  * The schema every wired addon publishes, as sources.
  *

package/dist/src/functions/db/local-db.js

@@ -10,7 +10,7 @@ import { applyPikkuSchemas, compilePikkuSchemas, pikkuSchemas, requiredPikkuSche
 import { loadAuthOptions, getAuthMigrations } from './better-auth-schema.js';
 import { generateSchemaTypes } from './db-codegen.js';
 import { generateZodTypes } from './zod-codegen.js';
-import { tableCreationSql } from '@pikku/migrator-sql';
+import { tableCreationSql, tablesInSourceOrder } from '@pikku/migrator-sql';
 import { SqliteMigrationExecutor } from '@pikku/migrator-sql/sqlite';
 import { SqliteIntrospector } from './sqlite/sqlite-introspector.js';
 import { createSqliteKysely } from './sqlite/sqlite-kysely.js';
@@ -114,13 +114,6 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir, dbConfig) {
     }
     return null;
 }
-/** @deprecated Use resolveDb(userConfig, ...) instead. */
-export function resolveLocalDb(sqliteDb, rootDir, outDir, runtimeDir) {
-    if (!sqliteDb)
-        return null;
-    const result = resolveDb({ sqliteDb }, rootDir, outDir, runtimeDir);
-    return result;
-}
 function resolveAgainst(root, p) {
     return isAbsolute(p) ? p : resolve(root, p);
 }
@@ -242,7 +235,14 @@ async function createEmbeddedPostgres(context, dataDir) {
         embeddedPostgresWasm,
         loadPGliteExtensions(context.rootDir, context.pgliteExtensions),
     ]);
-    return new PGlite({
+    // PGlite runs Postgres as an Emscripten module, and Emscripten's exit handler
+    // writes the WASM program's status straight to `process.exitCode` — booting a
+    // database leaves it at 99 even though nothing failed. The CLI's bin then
+    // ends with `process.exit(process.exitCode ?? 0)`, so any command that merely
+    // touched the embedded database reported failure after doing all of its work
+    // correctly. Restore whatever the process had before the boot.
+    const exitCodeBeforeBoot = process.exitCode;
+    const db = new PGlite({
         ...(dataDir ? { dataDir } : {}),
         ...wasm,
         extensions: {
@@ -250,6 +250,13 @@ async function createEmbeddedPostgres(context, dataDir) {
             ...declared,
         },
     });
+    await db.waitReady;
+    if (process.exitCode !== exitCodeBeforeBoot) {
+        // `?? 0` because assigning `undefined` does not clear an already-set
+        // exitCode under bun, which is the runtime the boot pollutes it on.
+        process.exitCode = exitCodeBeforeBoot ?? 0;
+    }
+    return db;
 }
 /**
  * PGlite reports an extension it was never given as a plain
@@ -1066,6 +1073,59 @@ export async function exportSchema(rootDir, pgliteExtensions = []) {
     }
     return artifact;
 }
+/**
+ * Write the artifact a consumer reads, whether or not this package has tables.
+ *
+ * An addon with no tables still publishes, because the consumer's only other
+ * reading of an absent file is "this package cannot say", which it must treat
+ * as a broken publish. The empty artifact is the addon stating, in a file that
+ * ships, that it needs nothing.
+ */
+export async function writeSchemaArtifact(rootDir, outDir, pgliteExtensions) {
+    const artifact = await exportSchema(rootDir, pgliteExtensions);
+    const file = join(outDir, 'db', 'pikku-db-meta.gen.json');
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+    return { file, dialects: Object.keys(artifact) };
+}
+/**
+ * Read and check one addon's published artifact.
+ *
+ * The file is generated, so a malformed one is not an authoring mistake to be
+ * explained away — it is a broken publish, and every branch here says which
+ * package to go and rebuild. Answering with half an artifact would be worse
+ * than refusing: a dialect carrying tables but no SQL generates a migration
+ * that creates nothing, and the schema silently drifts from what the addon's
+ * own functions expect.
+ */
+function readSchemaArtifact(artifactPath, pkg) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(artifactPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`The '${pkg}' addon publishes an unreadable ${ADDON_DB_ARTIFACT} ` +
+            `(${artifactPath}): ${error.message}. Rebuild the addon.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`The '${pkg}' addon publishes a ${ADDON_DB_ARTIFACT} that is not an ` +
+            'object of dialects. Rebuild the addon.');
+    }
+    for (const [dialect, exported] of Object.entries(parsed)) {
+        const entry = exported;
+        const hasSql = typeof entry?.sql === 'string' && entry.sql.trim().length > 0;
+        const hasTables = typeof entry?.tables === 'object' &&
+            entry.tables !== null &&
+            !Array.isArray(entry.tables);
+        if (!hasSql || !hasTables) {
+            throw new Error(`The '${pkg}' addon publishes a ${dialect} schema that is incomplete — ` +
+                `it needs both the SQL to run and the tables that SQL creates, and it ` +
+                `has ${!hasSql ? 'no sql' : 'sql'} and ${!hasTables ? 'no tables' : 'tables'}. ` +
+                'Rebuild the addon.');
+        }
+    }
+    return parsed;
+}
 /**
  * The schema every wired addon publishes, as sources.
  *
@@ -1089,11 +1149,23 @@ export async function addonSchemaSources(rootDir, dialect, addons, logger) {
             artifactPath = require.resolve(`${addon.package}/${ADDON_DB_ARTIFACT}`);
         }
         catch {
-            // Most addons have no schema at all, so an unresolvable artifact is the
-            // ordinary case and says nothing is contributed — not that anything failed.
-            continue;
+            // Every addon publishes this file, and one with no tables publishes an
+            // empty one. Absence is therefore never "contributes nothing" — it is a
+            // package that cannot say, and the two used to be indistinguishable:
+            // the addon was skipped in silence and the mistake surfaced much later,
+            // as a function querying a table nobody created.
+            throw new Error(`The '${addon.package}' addon does not publish ${ADDON_DB_ARTIFACT}, so ` +
+                'there is no way to tell whether it ships tables. Build it with a ' +
+                "current CLI (`pikku all` writes the file, empty when there are no " +
+                'tables), and make sure the package exports and packs it:\n' +
+                `  "exports": { "./${ADDON_DB_ARTIFACT}": "./dist/.pikku/addon/db/pikku-db-meta.gen.json" }\n` +
+                '  "files": ["dist"]');
         }
-        const artifact = JSON.parse(readFileSync(artifactPath, 'utf8'));
+        const artifact = readSchemaArtifact(artifactPath, addon.package);
+        // An addon with no tables says so with an empty artifact, which is the
+        // ordinary case and contributes nothing.
+        if (Object.keys(artifact).length === 0)
+            continue;
         const exported = artifact[dialect];
         if (!exported) {
             logger.error(`The '${addon.package}' addon publishes a schema, but not for ${dialect} — ` +
@@ -1232,7 +1304,7 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
         }
         else {
             const statements = [];
-            for (const table of missingTables) {
+            for (const table of tablesInSourceOrder(source.desired.sql, missingTables)) {
                 // A wholly new table is the first-time case in miniature: nothing to
                 // diff against, and the source's own SQL already says exactly how to
                 // build it. Rendering the column map instead would drop the primary

package/dist/src/functions/knowledge/render.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeIndexResult, KnowledgePlanDeferResult, KnowledgePlanProgressResult, KnowledgePlanSchemaResult, KnowledgePlanSetResult, KnowledgePlanShowResult, KnowledgeValidateResult } from '@pikku/knowledge';
+import type { KnowledgeIndexResult, KnowledgePlanDeferResult, KnowledgePlanProgressResult, KnowledgePlanSchemaResult, KnowledgePlanSetResult, KnowledgePlanShowResult, KnowledgeReconcileResult, KnowledgeValidateResult } from '@pikku/knowledge';
 export declare const renderKnowledgeValidate: (_services: unknown, { ok, notes, findings }: KnowledgeValidateResult) => void;
 export declare const renderKnowledgeIndex: (_services: unknown, { ok, check, files }: KnowledgeIndexResult) => void;
 export declare const renderKnowledgePlanSchema: (_services: unknown, { schema }: KnowledgePlanSchemaResult) => void;
@@ -6,3 +6,14 @@ export declare const renderKnowledgePlanShow: (_services: unknown, { ok, path, b
 export declare const renderKnowledgePlanProgress: (_services: unknown, { ok, path, message, done, missing, deferred, problems, }: KnowledgePlanProgressResult) => void;
 export declare const renderKnowledgePlanSet: (_services: unknown, { ok, path, problems, schema }: KnowledgePlanSetResult) => void;
 export declare const renderKnowledgePlanDefer: (_services: unknown, { ok, message }: KnowledgePlanDeferResult) => void;
+/**
+ * What to do next, and — when only a person can settle it — the question to put to
+ * them.
+ *
+ * The action's `reason` is machine wording that names the note and the frontmatter
+ * key; on `ask-user` it is deliberately NOT what gets printed as the question, because
+ * the reader there has never seen a note. The options are numbered rather than
+ * rendered as a picker: this is the fallback every harness has, and one that can do
+ * better reads the same answer as JSON.
+ */
+export declare const renderKnowledgeReconcile: (_services: unknown, { kind, reason, note, hold, notes, question }: KnowledgeReconcileResult) => void;

package/dist/src/functions/knowledge/render.js

@@ -138,3 +138,51 @@ export const renderKnowledgePlanDefer = (_services, { ok, message }) => {
     if (!ok)
         process.exitCode = 1;
 };
+/**
+ * What to do next, and — when only a person can settle it — the question to put to
+ * them.
+ *
+ * The action's `reason` is machine wording that names the note and the frontmatter
+ * key; on `ask-user` it is deliberately NOT what gets printed as the question, because
+ * the reader there has never seen a note. The options are numbered rather than
+ * rendered as a picker: this is the fallback every harness has, and one that can do
+ * better reads the same answer as JSON.
+ */
+export const renderKnowledgeReconcile = (_services, { kind, reason, note, hold, notes, question }) => {
+    if (kind === 'idle') {
+        console.log(`${dim('=')}  ${dim(reason)}`);
+        return;
+    }
+    const label = {
+        'repair-note': 'REPAIR',
+        'write-plan': 'PLAN',
+        'ask-user': 'ASK',
+        dispatch: 'BUILD',
+        hold: 'HELD',
+    };
+    const paint = kind === 'dispatch' ? added : kind === 'hold' ? dim : changed;
+    console.log(`${paint(label[kind] ?? kind.toUpperCase())}  ${note ?? ''}`.trim());
+    console.log();
+    if (question) {
+        console.log(`${dim(question.header)}`);
+        console.log(question.question);
+        question.options.forEach((option, index) => {
+            const description = option.description
+                ? `  ${dim(option.description)}`
+                : '';
+            console.log(`  ${index + 1}. ${option.label}${description}`);
+        });
+        if (question.options.length === 0)
+            console.log(dim('  (free text)'));
+        console.log();
+        console.log(`${dim('why:')}  ${dim(reason)}`);
+        return;
+    }
+    console.log(reason);
+    if (hold) {
+        console.log();
+        console.log(`${dim('held on:')}  ${hold}`);
+        for (const path of notes ?? [])
+            console.log(`  ${dim(path)}`);
+    }
+};

package/dist/src/functions/knowledge/schemas.d.ts

@@ -94,3 +94,26 @@ export declare const KnowledgePlanDeferOutputSchema: import("zod").ZodObject<{
     path: import("zod").ZodString;
     message: import("zod").ZodString;
 }, import("zod/v4/core").$strip>;
+export declare const KnowledgeReconcileInputSchema: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
+export declare const KnowledgeReconcileOutputSchema: import("zod").ZodObject<{
+    kind: import("zod").ZodEnum<{
+        idle: "idle";
+        "repair-note": "repair-note";
+        "write-plan": "write-plan";
+        "ask-user": "ask-user";
+        dispatch: "dispatch";
+        hold: "hold";
+    }>;
+    reason: import("zod").ZodString;
+    note: import("zod").ZodOptional<import("zod").ZodString>;
+    hold: import("zod").ZodOptional<import("zod").ZodString>;
+    notes: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    question: import("zod").ZodOptional<import("zod").ZodObject<{
+        header: import("zod").ZodString;
+        question: import("zod").ZodString;
+        options: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+            label: import("zod").ZodString;
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>;

package/dist/src/functions/knowledge/schemas.js

@@ -1,4 +1,4 @@
-import { KnowledgeIndexInput, KnowledgeIndexOutput, KnowledgePlanDeferInput, KnowledgePlanDeferOutput, KnowledgePlanProgressInput, KnowledgePlanProgressOutput, KnowledgePlanSchemaInput, KnowledgePlanSchemaOutput, KnowledgePlanSetInput, KnowledgePlanSetOutput, KnowledgePlanShowInput, KnowledgePlanShowOutput, KnowledgeValidateInput, KnowledgeValidateOutput, } from '@pikku/knowledge';
+import { KnowledgeIndexInput, KnowledgeIndexOutput, KnowledgePlanDeferInput, KnowledgePlanDeferOutput, KnowledgePlanProgressInput, KnowledgePlanProgressOutput, KnowledgePlanSchemaInput, KnowledgePlanSchemaOutput, KnowledgePlanSetInput, KnowledgePlanSetOutput, KnowledgePlanShowInput, KnowledgePlanShowOutput, KnowledgeReconcileInput, KnowledgeReconcileOutput, KnowledgeValidateInput, KnowledgeValidateOutput, } from '@pikku/knowledge';
 /**
  * The knowledge command schemas, re-bound to variables declared HERE rather than
  * imported straight into the command files.
@@ -33,3 +33,5 @@ export const KnowledgePlanSetInputSchema = KnowledgePlanSetInput;
 export const KnowledgePlanSetOutputSchema = KnowledgePlanSetOutput;
 export const KnowledgePlanDeferInputSchema = KnowledgePlanDeferInput;
 export const KnowledgePlanDeferOutputSchema = KnowledgePlanDeferOutput;
+export const KnowledgeReconcileInputSchema = KnowledgeReconcileInput;
+export const KnowledgeReconcileOutputSchema = KnowledgeReconcileOutput;

package/dist/src/functions/wirings/agent/pikku-command-agent.js

@@ -2,7 +2,7 @@ import { pikkuSessionlessFunc } from '#pikku/function';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
+import { writeWiringMeta } from '../../../utils/write-wiring-meta.js';
 import { serializeAgentMap } from './serialize-agent-map.js';
 import { serializeModelAliases } from './serialize-model-aliases.js';
 export const pikkuAgent = pikkuSessionlessFunc({
@@ -38,21 +38,18 @@ export const pikkuAgent = pikkuSessionlessFunc({
         const metaData = {
             agentsMeta: agents.agentsMeta,
         };
-        const minimalMeta = stripVerboseFields(metaData);
-        await writeFileInDir(logger, agentWiringMetaJsonFile, JSON.stringify(minimalMeta, null, 2));
-        if (hasVerboseFields(metaData)) {
-            const verbosePath = agentWiringMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json');
-            await writeFileInDir(logger, verbosePath, JSON.stringify(metaData, null, 2));
-        }
-        const jsonImportPath = getFileImportRelativePath(agentWiringMetaFile, agentWiringMetaJsonFile, packageMappings);
-        const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
-        const importStatement = supportsImportAttributes
-            ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
-            : `import metaData from '${jsonImportPath}'`;
-        await writeFileInDir(logger, agentWiringMetaFile, `import { pikkuState } from '@pikku/core/state'
+        await writeWiringMeta({
+            logger,
+            meta: metaData,
+            metaJsonFile: agentWiringMetaJsonFile,
+            metaFile: agentWiringMetaFile,
+            packageMappings,
+            supportsImportAttributes: schema?.supportsImportAttributes ?? false,
+            serializeMetaTS: ({ importStatement }) => `import { pikkuState } from '@pikku/core/state'
 import type { AgentsMeta } from '@pikku/core/agent'
 ${importStatement}
-pikkuState(${addonName ? `'${addonName}'` : 'null'}, 'agent', 'agentsMeta', metaData.agentsMeta as AgentsMeta)`);
+pikkuState(${addonName ? `'${addonName}'` : 'null'}, 'agent', 'agentsMeta', metaData.agentsMeta as AgentsMeta)`,
+        });
         await writeFileInDir(logger, agentMapDeclarationFile, serializeAgentMap(logger, agentMapDeclarationFile, packageMappings, functions.typesMap, agents.agentsMeta));
         return true;
     },