iranti 0.2.45 → 0.2.47

package/dist/scripts/iranti-cli.js

@@ -29,6 +29,7 @@ const backends_1 = require("../src/library/backends");
 const runtimeLifecycle_1 = require("../src/lib/runtimeLifecycle");
 const sdk_1 = require("../src/sdk");
 const queries_1 = require("../src/library/queries");
+const autoRemember_1 = require("../src/lib/autoRemember");
 class CliError extends Error {
     constructor(code, message, hints = [], details) {
         super(message);
@@ -766,12 +767,28 @@ async function inspectInstanceConfig(root, name) {
     let metaReadable = false;
     let envReadable = false;
     const ownershipIssues = [];
+    let rewrittenMeta = false;
     if (metaPresent) {
         try {
             const raw = await promises_1.default.readFile(metaFile, 'utf8');
             const parsed = JSON.parse(raw);
             metaReadable = typeof parsed.name === 'string' && parsed.name.trim().length > 0;
             if (metaReadable) {
+                const shouldRewriteOwnership = parsed.name?.trim() === name
+                    && ((typeof parsed.instanceDir === 'string' && path_1.default.resolve(parsed.instanceDir) !== path_1.default.resolve(instanceDir))
+                        || (typeof parsed.envFile === 'string' && path_1.default.resolve(parsed.envFile) !== path_1.default.resolve(envFile)));
+                if (shouldRewriteOwnership) {
+                    const nextMeta = {
+                        ...parsed,
+                        name,
+                        instanceDir,
+                        envFile,
+                    };
+                    await writeText(metaFile, `${JSON.stringify(nextMeta, null, 2)}\n`);
+                    rewrittenMeta = true;
+                    parsed.instanceDir = instanceDir;
+                    parsed.envFile = envFile;
+                }
                 if (parsed.name?.trim() !== name) {
                     ownershipIssues.push(`instance.json name is ${parsed.name}`);
                 }
@@ -781,6 +798,10 @@ async function inspectInstanceConfig(root, name) {
                 if (typeof parsed.envFile === 'string' && path_1.default.resolve(parsed.envFile) !== path_1.default.resolve(envFile)) {
                     ownershipIssues.push(`instance.json envFile points to ${parsed.envFile}`);
                 }
+                const databaseIntentValidation = parseInstanceDatabaseIntent(parsed.databaseIntent);
+                if (databaseIntentValidation.errors.length > 0) {
+                    ownershipIssues.push(`instance.json databaseIntent invalid: ${databaseIntentValidation.errors.join(', ')}`);
+                }
                 const dependencyValidation = (0, runtimeDependencies_1.parseInstanceDependencies)(parsed.dependencies);
                 if (dependencyValidation.errors.length > 0) {
                     ownershipIssues.push(`instance.json dependencies invalid: ${dependencyValidation.errors.join(', ')}`);
@@ -808,7 +829,9 @@ async function inspectInstanceConfig(root, name) {
     }
     else if (metaPresent && envPresent && metaReadable && envReadable) {
         classification = 'complete';
-        detail = 'instance metadata and env are present';
+        detail = rewrittenMeta
+            ? 'instance metadata was repaired and env is present'
+            : 'instance metadata and env are present';
     }
     else if ((metaPresent && !metaReadable) || (envPresent && !envReadable)) {
         classification = 'invalid';
@@ -1142,6 +1165,160 @@ function isLocalPostgresHost(hostname) {
     const normalized = hostname.trim().toLowerCase();
     return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1';
 }
+function parseDatabaseIntentStrategy(raw) {
+    const normalized = raw?.trim().toLowerCase() ?? '';
+    if (!normalized)
+        return null;
+    if (normalized === 'dedicated' || normalized === 'dedicated-local')
+        return 'dedicated-local';
+    if (normalized === 'shared' || normalized === 'shared-local')
+        return 'shared-local';
+    if (normalized === 'external' || normalized === 'managed' || normalized === 'external-existing')
+        return 'external-existing';
+    return null;
+}
+function parseDatabaseIntentStrategyFlag(raw, label) {
+    const trimmed = raw?.trim() ?? '';
+    if (!trimmed)
+        return null;
+    const parsed = parseDatabaseIntentStrategy(trimmed);
+    if (!parsed) {
+        throw new Error(`Invalid ${label} '${raw}'. Use dedicated, shared, or external.`);
+    }
+    return parsed;
+}
+function databaseIntentPromptValue(strategy) {
+    if (strategy === 'dedicated-local')
+        return 'dedicated';
+    if (strategy === 'shared-local')
+        return 'shared';
+    return 'external';
+}
+function describeDatabaseIntentStrategy(strategy) {
+    switch (strategy) {
+        case 'dedicated-local':
+            return 'dedicated local database';
+        case 'shared-local':
+            return 'shared local database';
+        case 'external-existing':
+        default:
+            return 'external existing database';
+    }
+}
+function inferDatabaseProvisioning(databaseUrl, dependencies = []) {
+    if (dependencies.some((dependency) => dependency.kind === 'docker-container')) {
+        return 'docker';
+    }
+    const parsed = parsePostgresConnectionString(databaseUrl);
+    return isLocalPostgresHost(parsed.hostname) ? 'local' : 'managed';
+}
+function inferDatabaseIntentStrategy(options) {
+    const databaseName = postgresDatabaseName(options.databaseUrl);
+    if (options.databaseMode === 'managed') {
+        return 'external-existing';
+    }
+    return databaseName === `iranti_${options.instanceName}`
+        ? 'dedicated-local'
+        : 'shared-local';
+}
+function buildInstanceDatabaseIntent(options) {
+    const parsed = parsePostgresConnectionString(options.databaseUrl);
+    const strategy = options.strategy ?? inferDatabaseIntentStrategy({
+        instanceName: options.instanceName,
+        databaseMode: options.databaseMode,
+        databaseUrl: options.databaseUrl,
+    });
+    const port = Number.parseInt(parsed.port || '5432', 10);
+    return {
+        strategy,
+        provisioning: options.databaseMode,
+        host: parsed.hostname,
+        ...(Number.isFinite(port) && port > 0 ? { port } : {}),
+        database: postgresDatabaseName(options.databaseUrl),
+        ...(options.dockerContainerName ? { dockerContainerName: options.dockerContainerName } : {}),
+    };
+}
+function parseInstanceDatabaseIntent(raw) {
+    if (raw === undefined || raw === null) {
+        return { intent: null, errors: [] };
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { intent: null, errors: ['databaseIntent must be an object'] };
+    }
+    const record = raw;
+    const strategy = parseDatabaseIntentStrategy(typeof record.strategy === 'string' ? record.strategy : undefined);
+    const provisioningRaw = typeof record.provisioning === 'string' ? record.provisioning.trim().toLowerCase() : '';
+    const provisioning = provisioningRaw === 'local' || provisioningRaw === 'managed' || provisioningRaw === 'docker'
+        ? provisioningRaw
+        : null;
+    const host = typeof record.host === 'string' ? record.host.trim() : '';
+    const database = typeof record.database === 'string' ? record.database.trim() : '';
+    const portRaw = typeof record.port === 'number'
+        ? record.port
+        : typeof record.port === 'string'
+            ? Number.parseInt(record.port, 10)
+            : undefined;
+    const dockerContainerName = typeof record.dockerContainerName === 'string'
+        ? record.dockerContainerName.trim()
+        : undefined;
+    const errors = [];
+    if (!strategy) {
+        errors.push('databaseIntent.strategy must be dedicated-local, shared-local, or external-existing');
+    }
+    if (!provisioning) {
+        errors.push('databaseIntent.provisioning must be local, managed, or docker');
+    }
+    if (!host) {
+        errors.push('databaseIntent.host is required');
+    }
+    if (!database) {
+        errors.push('databaseIntent.database is required');
+    }
+    if (portRaw !== undefined && (!Number.isFinite(portRaw) || portRaw <= 0)) {
+        errors.push('databaseIntent.port must be a positive integer');
+    }
+    if (errors.length > 0 || !strategy || !provisioning || !host || !database) {
+        return { intent: null, errors };
+    }
+    return {
+        intent: {
+            strategy,
+            provisioning,
+            host,
+            ...(portRaw !== undefined ? { port: portRaw } : {}),
+            database,
+            ...(dockerContainerName ? { dockerContainerName } : {}),
+        },
+        errors: [],
+    };
+}
+function resolveInstanceDatabaseIntent(options) {
+    const parsedMeta = parseInstanceDatabaseIntent(options.meta?.databaseIntent);
+    if (parsedMeta.intent) {
+        return { intent: parsedMeta.intent, source: 'meta', errors: parsedMeta.errors };
+    }
+    const dbUrl = options.env.DATABASE_URL?.trim();
+    if (!dbUrl || detectPlaceholder(dbUrl)) {
+        return { intent: null, source: 'none', errors: parsedMeta.errors };
+    }
+    const dockerDependency = options.dependencies.find((dependency) => dependency.kind === 'docker-container');
+    return {
+        intent: buildInstanceDatabaseIntent({
+            instanceName: options.instanceName,
+            databaseMode: inferDatabaseProvisioning(dbUrl, options.dependencies),
+            databaseUrl: dbUrl,
+            dockerContainerName: dockerDependency?.name,
+        }),
+        source: 'inferred',
+        errors: parsedMeta.errors,
+    };
+}
+function describeInstanceDatabaseIntent(intent, source = 'meta') {
+    const target = `${intent.host}${intent.port ? `:${intent.port}` : ''}/${intent.database}`;
+    const sourceSuffix = source === 'inferred' ? ' (inferred)' : '';
+    const dockerSuffix = intent.dockerContainerName ? `, container ${intent.dockerContainerName}` : '';
+    return `${describeDatabaseIntentStrategy(intent.strategy)} via ${intent.provisioning} -> ${target}${dockerSuffix}${sourceSuffix}`;
+}
 function sanitizeIdentifier(input, fallback) {
     const value = input.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
     if (!value && input.trim()) {
@@ -1286,6 +1463,7 @@ async function ensureInstanceConfigured(root, name, config) {
             port: config.port,
             envFile,
             instanceDir,
+            databaseIntent: config.databaseIntent,
             ...(config.dependencies && config.dependencies.length > 0 ? { dependencies: config.dependencies } : {}),
         };
         await writeJson(metaFile, meta);
@@ -1298,6 +1476,7 @@ async function ensureInstanceConfigured(root, name, config) {
         ...config.providerKeys,
     });
     await syncInstanceMeta(root, name, config.port, {
+        databaseIntent: config.databaseIntent,
         ...(config.dependencies !== undefined ? { dependencies: config.dependencies } : {}),
     });
     return { envFile, instanceDir, created };
@@ -1420,6 +1599,10 @@ function resolveRecentMessages(args) {
     }
     return [];
 }
+function resolveBackfillFile(args) {
+    const backfill = getFlag(args, 'backfill')?.trim();
+    return backfill ? path_1.default.resolve(backfill) : null;
+}
 function parsePositiveInteger(raw, label) {
     if (!raw)
         return undefined;
@@ -1529,7 +1712,10 @@ function printHandshakeResult(target, task, result) {
     console.log(`  memory facts  ${result.workingMemory.length}`);
     console.log(`  generated     ${result.briefGeneratedAt}`);
     console.log('');
-    console.log(`Rules: ${truncateText(result.operatingRules, 160)}`);
+    console.log('Rules:');
+    for (const line of result.operatingRules.split(/\r?\n/)) {
+        console.log(line.trim().length > 0 ? `  ${line}` : '');
+    }
     if (result.workingMemory.length === 0) {
         console.log('');
         console.log('No working memory entries loaded.');
@@ -1549,6 +1735,9 @@ function printAttendResult(target, latestMessage, result) {
     console.log(`  message       ${truncateText(latestMessage, 120)}`);
     console.log(`  inject        ${result.shouldInject ? 'yes' : 'no'}`);
     console.log(`  reason        ${result.reason}`);
+    if (result.bootstrap?.handshakePerformed) {
+        console.log(`  bootstrap     handshake auto-ran (${result.bootstrap.task})`);
+    }
     console.log(`  method        ${result.decision.method}`);
     console.log(`  confidence    ${result.decision.confidence}`);
     console.log(`  explanation   ${result.decision.explanation}`);
@@ -1879,12 +2068,24 @@ async function syncInstanceMeta(root, name, port, options = {}) {
     const existing = await readInstanceMetaFile(metaFile);
     const existingCreatedAt = typeof existing?.createdAt === 'string' ? existing.createdAt : undefined;
     const existingDependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(existing?.dependencies).dependencies;
+    const currentDependencies = options.dependencies ?? existingDependencies;
+    const env = fs_1.default.existsSync(envFile)
+        ? await readEnvFile(envFile).catch(() => ({}))
+        : {};
+    const resolvedDatabaseIntent = options.databaseIntent
+        ?? resolveInstanceDatabaseIntent({
+            instanceName: name,
+            env,
+            meta: existing,
+            dependencies: currentDependencies,
+        }).intent;
     const meta = {
         name,
         createdAt: existingCreatedAt ?? new Date().toISOString(),
         port,
         envFile,
         instanceDir,
+        ...(resolvedDatabaseIntent ? { databaseIntent: resolvedDatabaseIntent } : {}),
         ...(options.dependencies !== undefined
             ? { dependencies: options.dependencies }
             : existingDependencies.length > 0
@@ -1992,6 +2193,7 @@ async function executeSetupPlan(plan) {
     const configured = await ensureInstanceConfigured(plan.root, plan.instanceName, {
         port: plan.port,
         dbUrl: plan.databaseUrl,
+        databaseIntent: plan.databaseIntent,
         provider: plan.provider,
         providerKeys: plan.providerKeys,
         apiKey: plan.apiKey,
@@ -2070,6 +2272,7 @@ async function executeSetupPlan(plan) {
         port: plan.port,
         mode: plan.mode,
         databaseMode: plan.databaseMode,
+        databaseIntent: plan.databaseIntent,
         bindings,
     };
 }
@@ -2096,6 +2299,7 @@ function parseSetupConfig(filePath) {
                 ? 'local'
                 : (() => { throw new Error(`Unsupported databaseMode in setup config: ${databaseModeRaw}`); })();
     const databaseUrl = deriveDatabaseUrlForMode(databaseMode, instanceName, String(raw?.databaseUrl ?? raw?.dbUrl ?? '').trim());
+    const databaseIntentStrategy = parseDatabaseIntentStrategyFlag(String(raw?.databaseIntent ?? raw?.dbIntent ?? '').trim(), 'databaseIntent');
     const provider = normalizeProvider(String(raw?.provider ?? 'mock')) ?? 'mock';
     if (!isSupportedProvider(provider)) {
         throw new Error(`Unsupported provider in setup config: ${provider}`);
@@ -2134,6 +2338,13 @@ function parseSetupConfig(filePath) {
         port,
         databaseUrl,
         databaseMode,
+        databaseIntent: buildInstanceDatabaseIntent({
+            instanceName,
+            databaseMode,
+            databaseUrl,
+            strategy: databaseIntentStrategy,
+            dockerContainerName: typeof raw?.dockerContainerName === 'string' ? raw.dockerContainerName : undefined,
+        }),
         provider,
         providerKeys,
         apiKey,
@@ -2174,6 +2385,7 @@ function defaultsSetupPlan(args) {
         throw new Error(`Invalid --db-mode '${explicit}'. Use local, managed, or docker.`);
     })();
     const databaseUrl = deriveDatabaseUrlForMode(databaseMode, instanceName, (getFlag(args, 'db-url') ?? process.env.DATABASE_URL ?? '').trim());
+    const databaseIntentStrategy = parseDatabaseIntentStrategyFlag(getFlag(args, 'db-intent'), '--db-intent');
     const provider = normalizeProvider(getFlag(args, 'provider') ?? process.env.LLM_PROVIDER ?? 'mock') ?? 'mock';
     if (!isSupportedProvider(provider)) {
         throw new Error(`Unsupported provider '${provider}' for --defaults.`);
@@ -2215,6 +2427,13 @@ function defaultsSetupPlan(args) {
         port,
         databaseUrl,
         databaseMode,
+        databaseIntent: buildInstanceDatabaseIntent({
+            instanceName,
+            databaseMode,
+            databaseUrl,
+            strategy: databaseIntentStrategy,
+            dockerContainerName: getFlag(args, 'docker-container-name'),
+        }),
         provider,
         providerKeys,
         apiKey,
@@ -4137,6 +4356,7 @@ async function setupCommand(args) {
         console.log(`  instance url   http://localhost:${result.port}`);
         console.log(`  memory mode    ${result.mode}`);
         console.log(`  database mode  ${result.databaseMode}`);
+        console.log(`  db strategy    ${describeInstanceDatabaseIntent(result.databaseIntent)}`);
         if (result.bindings.length === 0) {
             console.log(`  projects       ${paint('none bound yet', 'yellow')}`);
         }
@@ -4224,6 +4444,9 @@ async function setupCommand(args) {
         const existingInstance = fs_1.default.existsSync(instancePaths(finalRoot, instanceName).envFile)
             ? await loadInstanceEnv(finalRoot, instanceName)
             : null;
+        const existingInstanceMeta = fs_1.default.existsSync(instancePaths(finalRoot, instanceName).metaFile)
+            ? await readInstanceMetaFile(instancePaths(finalRoot, instanceName).metaFile)
+            : null;
         if (existingInstance) {
             console.log(`${infoLabel()} Found existing instance '${instanceName}'. Updating it.`);
         }
@@ -4244,6 +4467,7 @@ async function setupCommand(args) {
         let databaseProvisioned = false;
         let dockerContainerName;
         let databaseMode = recommendedDatabaseMode;
+        let databaseIntentStrategy = null;
         printChoiceGuide('Database Mode Choices', [
             {
                 choice: 'local',
@@ -4283,6 +4507,13 @@ async function setupCommand(args) {
                         console.log(`${infoLabel()} Iranti will create the local database automatically if it does not already exist.`);
                     }
                 }
+                databaseIntentStrategy = parseDatabaseIntentStrategyFlag(await prompt.line('Database intent (dedicated, shared, external)', databaseIntentPromptValue(resolveInstanceDatabaseIntent({
+                    instanceName,
+                    env: existingInstance?.env ?? { DATABASE_URL: dbUrl },
+                    meta: existingInstanceMeta,
+                    dependencies: (0, runtimeDependencies_1.parseInstanceDependencies)(existingInstanceMeta?.dependencies).dependencies,
+                }).intent?.strategy
+                    ?? inferDatabaseIntentStrategy({ instanceName, databaseMode, databaseUrl: dbUrl }))), 'database intent');
                 bootstrapDatabase = await promptYesNo(prompt, 'Run migrations and seed the database now?', true);
                 break;
             }
@@ -4298,6 +4529,15 @@ async function setupCommand(args) {
                 const containerName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker container name', `iranti_${instanceName}_db`), `iranti_${instanceName}_db`);
                 dockerContainerName = containerName;
                 dbUrl = `postgresql://postgres:${dbPassword}@localhost:${dbHostPort}/${dbName}`;
+                databaseIntentStrategy = parseDatabaseIntentStrategyFlag(await prompt.line('Database intent (dedicated, shared, external)', databaseIntentPromptValue(resolveInstanceDatabaseIntent({
+                    instanceName,
+                    env: existingInstance?.env ?? { DATABASE_URL: dbUrl },
+                    meta: existingInstanceMeta,
+                    dependencies: dockerContainerName
+                        ? [{ kind: 'docker-container', name: dockerContainerName, ...(dbHostPort > 0 ? { healthTcpPort: dbHostPort } : {}) }]
+                        : (0, runtimeDependencies_1.parseInstanceDependencies)(existingInstanceMeta?.dependencies).dependencies,
+                }).intent?.strategy
+                    ?? inferDatabaseIntentStrategy({ instanceName, databaseMode, databaseUrl: dbUrl }))), 'database intent');
                 console.log(`${infoLabel()} Docker will be used only for PostgreSQL. Iranti itself does not require Docker once a PostgreSQL database is available.`);
                 if (await promptYesNo(prompt, `Start or reuse Docker container '${containerName}' now?`, true)) {
                     await runDockerPostgresContainer({
@@ -4442,6 +4682,13 @@ async function setupCommand(args) {
             port,
             databaseUrl: dbUrl,
             databaseMode,
+            databaseIntent: buildInstanceDatabaseIntent({
+                instanceName,
+                databaseMode,
+                databaseUrl: dbUrl,
+                strategy: databaseIntentStrategy,
+                dockerContainerName,
+            }),
             provider,
             providerKeys,
             apiKey: defaultApiKey,
@@ -4472,6 +4719,7 @@ async function setupCommand(args) {
     console.log(`  instance url   http://localhost:${finalResult.port}`);
     console.log(`  memory mode    ${finalResult.mode}`);
     console.log(`  database mode  ${finalResult.databaseMode}`);
+    console.log(`  db strategy    ${describeInstanceDatabaseIntent(finalResult.databaseIntent)}`);
     if (finalResult.bindings.length === 0) {
         console.log(`  projects       ${paint('none bound yet', 'yellow')}`);
     }
@@ -5236,6 +5484,12 @@ async function showInstanceCommand(args) {
         : {};
     const meta = await readInstanceMetaFile(instancePaths(root, name).metaFile);
     const dependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(meta?.dependencies).dependencies;
+    const databaseIntent = resolveInstanceDatabaseIntent({
+        instanceName: name,
+        env,
+        meta,
+        dependencies,
+    });
     const runtime = await readInstanceRuntimeSummary(root, name);
     console.log(bold(`Instance: ${name}`));
     console.log(`  dir : ${instanceDir}`);
@@ -5243,6 +5497,9 @@ async function showInstanceCommand(args) {
     console.log(`  config: ${describeInstanceConfig(config)}`);
     console.log(`  port: ${env.IRANTI_PORT ?? '3001'}`);
     console.log(`  db  : ${env.DATABASE_URL ?? '(missing)'}`);
+    if (databaseIntent.intent) {
+        console.log(`  db strategy: ${describeInstanceDatabaseIntent(databaseIntent.intent, databaseIntent.source)}`);
+    }
     console.log(`  esc : ${env.IRANTI_ESCALATION_DIR ?? '(missing)'}`);
     if (dependencies.length > 0) {
         console.log(`  deps: ${dependencies.map((dependency) => (0, runtimeDependencies_1.describeInstanceDependency)(dependency)).join(', ')}`);
@@ -5371,6 +5628,12 @@ async function configureInstanceCommand(args) {
     const { instanceDir, envFile, env, config } = await loadInstanceEnv(root, name, { allowRepair: true });
     const currentMeta = await readInstanceMetaFile(instancePaths(root, name).metaFile);
     const currentDependencies = (0, runtimeDependencies_1.parseInstanceDependencies)(currentMeta?.dependencies).dependencies;
+    const currentDatabaseIntent = resolveInstanceDatabaseIntent({
+        instanceName: name,
+        env,
+        meta: currentMeta,
+        dependencies: currentDependencies,
+    });
     const updates = {};
     let portRaw = getFlag(args, 'port');
     let dbUrl = getFlag(args, 'db-url');
@@ -5380,6 +5643,7 @@ async function configureInstanceCommand(args) {
     let clearProviderKey = hasFlag(args, 'clear-provider-key');
     let dockerContainerName = getFlag(args, 'docker-container');
     let dockerHealthPortRaw = getFlag(args, 'docker-health-port');
+    let dbIntentRaw = getFlag(args, 'db-intent');
     const clearDockerContainer = hasFlag(args, 'clear-docker-container');
     if (hasFlag(args, 'interactive')) {
         await withPromptSession(async (prompt) => {
@@ -5387,12 +5651,14 @@ async function configureInstanceCommand(args) {
                 'This updates one existing instance in place.',
                 'API port controls where the Iranti API listens.',
                 'DATABASE_URL points at the PostgreSQL database for this instance.',
+                'Database intent tells Iranti whether this should be treated as a dedicated local DB, a shared local DB, or an external existing DB.',
                 'LLM provider and provider key control which model backend Iranti uses.',
                 'Iranti API key is the client credential other tools and project bindings use to authenticate.',
                 'Optional Docker dependency settings let `iranti run --instance` start a recorded backing container before the API boots.',
             ]);
             portRaw = await prompt.line('API port', portRaw ?? env.IRANTI_PORT);
             dbUrl = await prompt.line('DATABASE_URL', dbUrl ?? env.DATABASE_URL);
+            dbIntentRaw = await prompt.line('Database intent (dedicated, shared, external)', dbIntentRaw ?? databaseIntentPromptValue(currentDatabaseIntent.intent?.strategy));
             providerInput = await prompt.line('LLM provider', providerInput ?? env.LLM_PROVIDER ?? 'mock');
             const interactiveProvider = normalizeProvider(providerInput ?? env.LLM_PROVIDER ?? 'mock');
             const interactiveProviderEnvKey = providerKeyEnv(interactiveProvider);
@@ -5415,6 +5681,7 @@ async function configureInstanceCommand(args) {
     }
     if (dbUrl)
         updates.DATABASE_URL = dbUrl;
+    const requestedDatabaseIntent = parseDatabaseIntentStrategyFlag(dbIntentRaw, '--db-intent');
     if (apiKey)
         updates.IRANTI_API_KEY = apiKey;
     const provider = normalizeProvider(providerInput ?? env.LLM_PROVIDER ?? 'mock');
@@ -5467,8 +5734,9 @@ async function configureInstanceCommand(args) {
     }
     if (Object.keys(updates).length === 0) {
         const dependenciesUnchanged = JSON.stringify(nextDependencies) === JSON.stringify(currentDependencies);
-        if (dependenciesUnchanged) {
-            throw new Error('No changes provided. Use flags like --provider, --provider-key, --api-key, --db-url, --port, or the Docker dependency flags.');
+        const databaseIntentUnchanged = requestedDatabaseIntent === null;
+        if (dependenciesUnchanged && databaseIntentUnchanged) {
+            throw new Error('No changes provided. Use flags like --provider, --provider-key, --api-key, --db-url, --db-intent, --port, or the Docker dependency flags.');
         }
     }
     const nextEnv = { ...env };
@@ -5488,9 +5756,19 @@ async function configureInstanceCommand(args) {
     if (!nextEnv.DATABASE_URL?.trim()) {
         throw cliError('IRANTI_INSTANCE_DATABASE_REQUIRED', `Instance '${name}' still needs DATABASE_URL before it can be considered repaired.`, ['Pass `--db-url <postgresql://...>` or rerun `iranti configure instance <name> --interactive`.'], { instance: name, envFile, config: config.classification });
     }
+    const nextDatabaseIntent = buildInstanceDatabaseIntent({
+        instanceName: name,
+        databaseMode: inferDatabaseProvisioning(nextEnv.DATABASE_URL, nextDependencies),
+        databaseUrl: nextEnv.DATABASE_URL,
+        strategy: requestedDatabaseIntent ?? currentDatabaseIntent.intent?.strategy,
+        dockerContainerName: nextDependencies.find((dependency) => dependency.kind === 'docker-container')?.name,
+    });
     await ensureDir(instanceDir);
     await upsertEnvFile(envFile, updates);
-    await syncInstanceMeta(root, name, nextPort, { dependencies: nextDependencies });
+    await syncInstanceMeta(root, name, nextPort, {
+        dependencies: nextDependencies,
+        databaseIntent: nextDatabaseIntent,
+    });
     const json = hasFlag(args, 'json');
     const result = {
         instance: name,
@@ -5499,6 +5777,7 @@ async function configureInstanceCommand(args) {
         provider: updates.LLM_PROVIDER ?? env.LLM_PROVIDER ?? 'mock',
         apiKeyChanged: Boolean(apiKey),
         providerKeyChanged: Boolean(providerKey) || hasFlag(args, 'clear-provider-key'),
+        databaseIntent: nextDatabaseIntent.strategy,
         dependencies: nextDependencies.map((dependency) => (0, runtimeDependencies_1.describeInstanceDependency)(dependency)),
     };
     if (json) {
@@ -5509,6 +5788,7 @@ async function configureInstanceCommand(args) {
     console.log(`  status   ${okLabel()}`);
     console.log(`  env      ${envFile}`);
     console.log(`  keys     ${result.updatedKeys.join(', ')}`);
+    console.log(`  db       ${describeInstanceDatabaseIntent(nextDatabaseIntent)}`);
     if (result.dependencies.length > 0) {
         console.log(`  deps     ${result.dependencies.join(', ')}`);
     }
@@ -5745,172 +6025,224 @@ async function resolveCommand(args) {
     await (0, resolutionist_1.resolveInteractive)(escalationDir);
 }
 async function handshakeCommand(args) {
-    const json = hasFlag(args, 'json');
-    const target = await resolveAttendantCliTarget(args);
-    const task = getFlag(args, 'task')?.trim() || 'CLI handshake';
-    const recentMessages = resolveRecentMessages(args);
-    const result = await target.iranti.handshake({
-        agent: target.agentId,
-        task,
-        recentMessages,
-    });
-    if (json) {
-        console.log(JSON.stringify({
+    try {
+        const json = hasFlag(args, 'json');
+        const target = await resolveAttendantCliTarget(args);
+        const task = getFlag(args, 'task')?.trim() || 'CLI handshake';
+        let recentMessages = resolveRecentMessages(args);
+        const backfillFile = resolveBackfillFile(args);
+        let backfillResult = null;
+        if (backfillFile) {
+            const content = fs_1.default.readFileSync(backfillFile, 'utf-8');
+            backfillResult = await (0, autoRemember_1.backfillChatHistory)({
+                iranti: target.iranti,
+                content,
+                agent: target.agentId,
+                source: 'CLIBackfill',
+            });
+            if (recentMessages.length === 0) {
+                recentMessages = (0, autoRemember_1.parseBackfillChatTranscript)(content)
+                    .map((message) => message.text.trim())
+                    .filter(Boolean)
+                    .slice(-12);
+            }
+        }
+        const result = await target.iranti.handshake({
             agent: target.agentId,
-            envSource: target.envSource,
-            envFile: target.envFile,
             task,
             recentMessages,
-            result,
-        }, null, 2));
-        return;
+        });
+        if (json) {
+            console.log(JSON.stringify({
+                agent: target.agentId,
+                envSource: target.envSource,
+                envFile: target.envFile,
+                task,
+                backfillFile,
+                backfillResult,
+                recentMessages,
+                result,
+            }, null, 2));
+            return;
+        }
+        printHandshakeResult(target, task, result);
+        if (backfillResult) {
+            console.log('');
+            console.log('Backfill:');
+            console.log(`  file          ${backfillFile}`);
+            console.log(`  messages      ${backfillResult.messagesParsed}`);
+            console.log(`  extracted     ${backfillResult.extracted}`);
+            console.log(`  written       ${backfillResult.written}`);
+            if (backfillResult.skipped.length > 0) {
+                console.log(`  skipped       ${backfillResult.skipped.length}`);
+            }
+        }
+        if (result.backfillSuggestion?.suggested && !backfillFile) {
+            console.log('');
+            console.log('Backfill suggestion:');
+            console.log(`  reason        ${result.backfillSuggestion.reason}`);
+            console.log(`  candidateFacts ${result.backfillSuggestion.candidateFacts}`);
+            console.log(`  sample keys   ${result.backfillSuggestion.sampleKeys.join(', ')}`);
+            console.log(`  command       ${result.backfillSuggestion.suggestedCommand}`);
+        }
+        console.log('');
+        console.log(`${infoLabel()} This is a manual Attendant inspection tool. Claude Code should still use hooks + MCP in normal operation.`);
+    }
+    finally {
+        await (0, client_1.disconnectDb)().catch(() => undefined);
     }
-    printHandshakeResult(target, task, result);
-    console.log('');
-    console.log(`${infoLabel()} This is a manual Attendant inspection tool. Claude Code should still use hooks + MCP in normal operation.`);
 }
 async function attendCommand(args) {
-    const json = hasFlag(args, 'json');
-    const target = await resolveAttendantCliTarget(args);
-    const latestMessage = resolveAttendMessage(args);
-    const currentContext = resolveContextText(args);
-    const maxFacts = parsePositiveInteger(getFlag(args, 'max-facts'), 'max-facts');
-    const entityHint = getFlag(args, 'entity-hint')?.trim();
-    if (entityHint && !entityHint.includes('/')) {
-        throw new Error('entity-hint must use entityType/entityId format.');
-    }
-    const result = await target.iranti.attend({
-        agent: target.agentId,
-        currentContext,
-        latestMessage,
-        forceInject: hasFlag(args, 'force'),
-        maxFacts,
-        entityHints: entityHint ? [entityHint] : undefined,
-    });
-    if (json) {
-        console.log(JSON.stringify({
+    try {
+        const json = hasFlag(args, 'json');
+        const target = await resolveAttendantCliTarget(args);
+        const latestMessage = resolveAttendMessage(args);
+        const currentContext = resolveContextText(args);
+        const maxFacts = parsePositiveInteger(getFlag(args, 'max-facts'), 'max-facts');
+        const entityHint = getFlag(args, 'entity-hint')?.trim();
+        if (entityHint && !entityHint.includes('/')) {
+            throw new Error('entity-hint must use entityType/entityId format.');
+        }
+        const result = await target.iranti.attend({
             agent: target.agentId,
-            envSource: target.envSource,
-            envFile: target.envFile,
-            latestMessage,
             currentContext,
-            maxFacts: maxFacts ?? null,
-            entityHints: entityHint ? [entityHint] : [],
+            latestMessage,
             forceInject: hasFlag(args, 'force'),
-            result,
-        }, null, 2));
-        return;
-    }
-    printAttendResult(target, latestMessage, result);
-    console.log('');
-    console.log(`${infoLabel()} This is a manual Attendant inspection tool. Claude Code should still use hooks + MCP in normal operation.`);
-}
-async function handoffCommand(args) {
-    const json = hasFlag(args, 'json');
-    const target = await resolveAttendantCliTarget(args);
-    const taskEntity = resolveTaskEntity(args);
-    const projectEntity = getFlag(args, 'project-entity')?.trim();
-    if (projectEntity && !projectEntity.includes('/')) {
-        throw new Error('project-entity must use entityType/entityId format.');
-    }
-    const nextStep = getFlag(args, 'next-step')?.trim();
-    if (!nextStep) {
-        throw new Error('Missing --next-step. A standardized handoff must record the receiver action.');
-    }
-    const status = getFlag(args, 'status')?.trim() || 'ready_for_handoff';
-    const owner = getFlag(args, 'owner')?.trim();
-    const blockers = parseDelimitedList(getFlag(args, 'blockers'));
-    const artifacts = parseDelimitedList(getFlag(args, 'artifacts'));
-    const notes = getFlag(args, 'notes')?.trim();
-    const source = getFlag(args, 'source')?.trim() || 'CLIHandoff';
-    const confidence = parsePositiveInteger(getFlag(args, 'confidence'), 'confidence') ?? 95;
-    if (confidence > 100) {
-        throw new Error('confidence must be <= 100.');
-    }
-    const writes = [];
-    writes.push({
-        entity: taskEntity,
-        key: 'status',
-        value: { state: status },
-        summary: buildHandoffSummary('status', { state: status }),
-    });
-    writes.push({
-        entity: taskEntity,
-        key: 'next_step',
-        value: { instruction: nextStep },
-        summary: buildHandoffSummary('next_step', { instruction: nextStep }),
-    });
-    if (owner) {
-        writes.push({
-            entity: taskEntity,
-            key: 'current_owner',
-            value: { agentId: owner },
-            summary: buildHandoffSummary('current_owner', { agentId: owner }),
+            maxFacts,
+            entityHints: entityHint ? [entityHint] : undefined,
         });
+        if (json) {
+            console.log(JSON.stringify({
+                agent: target.agentId,
+                envSource: target.envSource,
+                envFile: target.envFile,
+                latestMessage,
+                currentContext,
+                maxFacts: maxFacts ?? null,
+                entityHints: entityHint ? [entityHint] : [],
+                forceInject: hasFlag(args, 'force'),
+                result,
+            }, null, 2));
+            return;
+        }
+        printAttendResult(target, latestMessage, result);
+        console.log('');
+        console.log(`${infoLabel()} This is a manual Attendant inspection tool. Claude Code should still use hooks + MCP in normal operation.`);
     }
-    if (blockers.length > 0) {
-        writes.push({
-            entity: taskEntity,
-            key: 'blockers',
-            value: { items: blockers },
-            summary: buildHandoffSummary('blockers', { items: blockers }),
-        });
+    finally {
+        await (0, client_1.disconnectDb)().catch(() => undefined);
     }
-    if (artifacts.length > 0) {
+}
+async function handoffCommand(args) {
+    try {
+        const json = hasFlag(args, 'json');
+        const target = await resolveAttendantCliTarget(args);
+        const taskEntity = resolveTaskEntity(args);
+        const projectEntity = getFlag(args, 'project-entity')?.trim();
+        if (projectEntity && !projectEntity.includes('/')) {
+            throw new Error('project-entity must use entityType/entityId format.');
+        }
+        const nextStep = getFlag(args, 'next-step')?.trim();
+        if (!nextStep) {
+            throw new Error('Missing --next-step. A standardized handoff must record the receiver action.');
+        }
+        const status = getFlag(args, 'status')?.trim() || 'ready_for_handoff';
+        const owner = getFlag(args, 'owner')?.trim();
+        const blockers = parseDelimitedList(getFlag(args, 'blockers'));
+        const artifacts = parseDelimitedList(getFlag(args, 'artifacts'));
+        const notes = getFlag(args, 'notes')?.trim();
+        const source = getFlag(args, 'source')?.trim() || 'CLIHandoff';
+        const confidence = parsePositiveInteger(getFlag(args, 'confidence'), 'confidence') ?? 95;
+        if (confidence > 100) {
+            throw new Error('confidence must be <= 100.');
+        }
+        const writes = [];
         writes.push({
             entity: taskEntity,
-            key: 'artifacts',
-            value: { files: artifacts },
-            summary: buildHandoffSummary('artifacts', { files: artifacts }),
+            key: 'status',
+            value: { state: status },
+            summary: buildHandoffSummary('status', { state: status }),
         });
-    }
-    if (notes) {
         writes.push({
             entity: taskEntity,
-            key: 'notes',
-            value: { text: notes },
-            summary: buildHandoffSummary('notes', { text: notes }),
-        });
-    }
-    if (projectEntity) {
-        writes.push({
-            entity: projectEntity,
-            key: 'active_handoff_task',
-            value: {
-                taskEntity,
-                owner: owner ?? null,
-                status,
-                updatedBy: target.agentId,
-            },
-            summary: buildHandoffSummary('active_handoff_task', { taskEntity }),
-        });
-    }
-    for (const write of writes) {
-        await target.iranti.write({
-            entity: write.entity,
-            key: write.key,
-            value: write.value,
-            summary: write.summary,
-            confidence,
-            source,
-            agent: target.agentId,
+            key: 'next_step',
+            value: { instruction: nextStep },
+            summary: buildHandoffSummary('next_step', { instruction: nextStep }),
         });
+        if (owner) {
+            writes.push({
+                entity: taskEntity,
+                key: 'current_owner',
+                value: { agentId: owner },
+                summary: buildHandoffSummary('current_owner', { agentId: owner }),
+            });
+        }
+        if (blockers.length > 0) {
+            writes.push({
+                entity: taskEntity,
+                key: 'blockers',
+                value: { items: blockers },
+                summary: buildHandoffSummary('blockers', { items: blockers }),
+            });
+        }
+        if (artifacts.length > 0) {
+            writes.push({
+                entity: taskEntity,
+                key: 'artifacts',
+                value: { files: artifacts },
+                summary: buildHandoffSummary('artifacts', { files: artifacts }),
+            });
+        }
+        if (notes) {
+            writes.push({
+                entity: taskEntity,
+                key: 'notes',
+                value: { text: notes },
+                summary: buildHandoffSummary('notes', { text: notes }),
+            });
+        }
+        if (projectEntity) {
+            writes.push({
+                entity: projectEntity,
+                key: 'active_handoff_task',
+                value: {
+                    taskEntity,
+                    owner: owner ?? null,
+                    status,
+                    updatedBy: target.agentId,
+                },
+                summary: buildHandoffSummary('active_handoff_task', { taskEntity }),
+            });
+        }
+        for (const write of writes) {
+            await target.iranti.write({
+                entity: write.entity,
+                key: write.key,
+                value: write.value,
+                summary: write.summary,
+                confidence,
+                source,
+                agent: target.agentId,
+            });
+        }
+        if (json) {
+            console.log(JSON.stringify({
+                agent: target.agentId,
+                envSource: target.envSource,
+                envFile: target.envFile,
+                source,
+                confidence,
+                writes,
+            }, null, 2));
+            return;
+        }
+        printHandoffResult(target, taskEntity, writes);
+        console.log('');
+        console.log(`${infoLabel()} Handoffs are shared-memory facts. Pair this with checkpoint() if the sender also needs agent-local recovery.`);
     }
-    if (json) {
-        console.log(JSON.stringify({
-            agent: target.agentId,
-            envSource: target.envSource,
-            envFile: target.envFile,
-            source,
-            confidence,
-            writes,
-        }, null, 2));
-        process.exit(0);
+    finally {
+        await (0, client_1.disconnectDb)().catch(() => undefined);
     }
-    printHandoffResult(target, taskEntity, writes);
-    console.log('');
-    console.log(`${infoLabel()} Handoffs are shared-memory facts. Pair this with checkpoint() if the sender also needs agent-local recovery.`);
-    process.exit(0);
 }
 function printClaudeSetupHelp() {
     console.log([