iranti 0.2.45 → 0.2.46

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(', ')}`);
     }
@@ -5748,7 +6028,24 @@ 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);
+    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,
         task,
@@ -5760,12 +6057,33 @@ async function handshakeCommand(args) {
             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.`);
 }

package/dist/scripts/iranti-mcp.js

@@ -62,6 +62,7 @@ function printHelp() {
         '  IRANTI_AUTO_REMEMBER         Opt-in explicit prompt auto-save before attend()',
         '',
         'This server is intended for Claude Code and other MCP clients over stdio.',
+        'If you run `iranti mcp` directly in a terminal, it will stay running and wait for an MCP client.',
     ].join('\n'));
 }
 function requireConnectionString() {
@@ -135,6 +136,9 @@ function normalizeRecentMessages(messages) {
         .filter(Boolean)
         .slice(-12);
 }
+function isInteractiveTerminalLaunch() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 async function main() {
     if (process.argv.includes('--help') || process.argv.includes('-h')) {
         printHelp();
@@ -147,13 +151,15 @@ async function main() {
     await ensureDefaultAgent(iranti);
     const server = new mcp_js_1.McpServer({
         name: 'iranti-mcp',
-        version: '0.2.45',
+        version: '0.2.46',
     });
     server.registerTool('iranti_handshake', {
         description: `Initialize or refresh an agent's working-memory brief for the current task.
 Call this at session start or when a new task begins, passing the task and
 recent messages. Returns operating rules plus prioritized relevant memory
-for that task. Do not use this as a per-turn retrieval tool; use iranti_attend.`,
+for that task. If the recent messages appear to contain durable facts that
+are not yet in shared memory, the result may include a backfill suggestion.
+Do not use this as a per-turn retrieval tool; use iranti_attend.`,
         inputSchema: {
             task: z.string().min(1).describe('The current task or objective.'),
             recentMessages: z.array(z.string()).optional().describe('Recent conversation messages.'),
@@ -174,7 +180,9 @@ visible context window. If the user is asking you to recall a remembered
 fact (for example a preference, decision, blocker, next step, or prior
 project detail), use this before answering instead of guessing or saying
 you do not know. Returns an injection decision plus any facts that should
-be added to context if relevant memory is missing.
+be added to context if relevant memory is missing. If no handshake has been
+performed yet for this agent in the current process, attend will auto-bootstrap
+the session first and report that in the result metadata.
 Omitting currentContext falls back to latestMessage only; pass the
 full visible context when available.`,
         inputSchema: {
@@ -387,6 +395,9 @@ this for arbitrary prose or every turn.`,
         const result = await iranti.whoKnows(entity);
         return textResult(result);
     });
+    if (isInteractiveTerminalLaunch()) {
+        console.error('[iranti-mcp] stdio server running; waiting for an MCP client. Press Ctrl+C to exit.');
+    }
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
 }