iranti 0.2.21 → 0.2.23

package/dist/scripts/iranti-cli.js

@@ -6,16 +6,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const promises_1 = __importDefault(require("fs/promises"));
-const https_1 = __importDefault(require("https"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const https_1 = __importDefault(require("https"));
 const promises_2 = __importDefault(require("readline/promises"));
 const stream_1 = require("stream");
 const net_1 = __importDefault(require("net"));
 const client_1 = require("../src/library/client");
 const apiKeys_1 = require("../src/security/apiKeys");
 const escalationPaths_1 = require("../src/lib/escalationPaths");
+const dockerCliParsing_1 = require("../src/lib/dockerCliParsing");
 const runtimeEnv_1 = require("../src/lib/runtimeEnv");
 const resolutionist_1 = require("../src/resolutionist");
 const chat_1 = require("../src/chat");
@@ -55,6 +56,31 @@ const ANSI = {
 };
 let CLI_DEBUG = process.argv.includes('--debug') || process.env.IRANTI_DEBUG === '1';
 let CLI_VERBOSE = CLI_DEBUG || process.argv.includes('--verbose') || process.env.IRANTI_VERBOSE === '1';
+// H-7: Cleanup/rollback stack — LIFO handlers run on SIGINT/SIGTERM to undo partial multi-step operations
+const _cleanupStack = [];
+function pushCleanup(fn) {
+    _cleanupStack.push(fn);
+}
+function popCleanup() {
+    _cleanupStack.pop();
+}
+async function runCleanupStack() {
+    while (_cleanupStack.length > 0) {
+        const fn = _cleanupStack.pop();
+        try {
+            await fn();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[cleanup] Error during rollback: ${msg}\n`);
+        }
+    }
+}
+for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => {
+        void runCleanupStack().finally(() => process.exit(130));
+    });
+}
 function useColor() {
     return Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
 }
@@ -173,20 +199,172 @@ function defaultInstallRoot(scope) {
     return path_1.default.join(os_1.default.homedir(), '.local', 'share', 'iranti');
 }
 function resolveInstallRoot(args, scope) {
+    return resolveInstallRootDetails(args, scope).root;
+}
+function walkAncestorPaths(startDir) {
+    const dirs = [];
+    let current = path_1.default.resolve(startDir);
+    while (true) {
+        dirs.push(current);
+        const parent = path_1.default.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+function findClosestAncestorFile(startDir, fileName) {
+    for (const dir of walkAncestorPaths(startDir)) {
+        const candidate = path_1.default.join(dir, fileName);
+        if (fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function findClosestAncestorRuntimeRoot(startDir) {
+    for (const dir of walkAncestorPaths(startDir)) {
+        for (const runtimeDirName of ['.iranti-runtime', '.iranti']) {
+            const candidate = path_1.default.join(dir, runtimeDirName);
+            if (fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isDirectory()) {
+                return path_1.default.resolve(candidate);
+            }
+        }
+    }
+    return null;
+}
+function resolveInstallRootDetails(args, scope) {
     const explicit = getFlag(args, 'root') ?? process.env.IRANTI_HOME;
-    if (explicit)
-        return path_1.default.resolve(explicit);
+    if (explicit) {
+        return {
+            root: path_1.default.resolve(explicit),
+            source: getFlag(args, 'root') ? 'flag' : 'env',
+            userRoot: defaultInstallRoot('user'),
+            systemRoot: defaultInstallRoot('system'),
+            installMetaPath: path_1.default.join(path_1.default.resolve(explicit), 'install.json'),
+        };
+    }
     const userRoot = defaultInstallRoot('user');
     const systemRoot = defaultInstallRoot('system');
     const userMeta = path_1.default.join(userRoot, 'install.json');
     const systemMeta = path_1.default.join(systemRoot, 'install.json');
-    if (scope === 'system')
-        return systemRoot;
-    if (fs_1.default.existsSync(userMeta))
-        return userRoot;
-    if (fs_1.default.existsSync(systemMeta))
-        return systemRoot;
-    return userRoot;
+    const cwd = process.cwd();
+    const projectBindingFile = findClosestAncestorFile(cwd, '.env.iranti');
+    const localRuntimeRoot = findClosestAncestorRuntimeRoot(cwd);
+    if (scope === 'system') {
+        return {
+            root: systemRoot,
+            source: 'default-system',
+            userRoot,
+            systemRoot,
+            installMetaPath: systemMeta,
+        };
+    }
+    if (projectBindingFile && fs_1.default.existsSync(projectBindingFile)) {
+        try {
+            const raw = fs_1.default.readFileSync(projectBindingFile, 'utf-8');
+            const match = raw.match(/^\s*IRANTI_INSTANCE_ENV\s*=\s*(.+)\s*$/m);
+            const value = match?.[1]?.trim().replace(/^['"]|['"]$/g, '');
+            const boundRoot = inferRuntimeRootFromInstanceEnv(value);
+            if (boundRoot && fs_1.default.existsSync(boundRoot)) {
+                return {
+                    root: boundRoot,
+                    source: 'project-binding',
+                    userRoot,
+                    systemRoot,
+                    installMetaPath: path_1.default.join(boundRoot, 'install.json'),
+                };
+            }
+        }
+        catch {
+            // Fall through to other resolution strategies.
+        }
+    }
+    if (localRuntimeRoot) {
+        return {
+            root: localRuntimeRoot,
+            source: 'cwd-runtime',
+            userRoot,
+            systemRoot,
+            installMetaPath: path_1.default.join(localRuntimeRoot, 'install.json'),
+        };
+    }
+    if (fs_1.default.existsSync(userMeta)) {
+        return {
+            root: userRoot,
+            source: 'user-install-meta',
+            userRoot,
+            systemRoot,
+            installMetaPath: userMeta,
+        };
+    }
+    if (fs_1.default.existsSync(systemMeta)) {
+        return {
+            root: systemRoot,
+            source: 'system-install-meta',
+            userRoot,
+            systemRoot,
+            installMetaPath: systemMeta,
+        };
+    }
+    return {
+        root: userRoot,
+        source: 'default-user',
+        userRoot,
+        systemRoot,
+        installMetaPath: userMeta,
+    };
+}
+function describeRuntimeRootSource(source) {
+    switch (source) {
+        case 'flag':
+            return '--root flag';
+        case 'env':
+            return 'IRANTI_HOME';
+        case 'project-binding':
+            return 'project binding';
+        case 'cwd-runtime':
+            return 'cwd runtime root';
+        case 'user-install-meta':
+            return 'user install metadata';
+        case 'system-install-meta':
+            return 'system install metadata';
+        case 'default-system':
+            return 'system default';
+        case 'default-user':
+        default:
+            return 'user default';
+    }
+}
+function inferRuntimeRootFromInstanceEnv(instanceEnvFile) {
+    if (!instanceEnvFile)
+        return null;
+    const normalized = path_1.default.resolve(instanceEnvFile);
+    if (path_1.default.basename(normalized).toLowerCase() !== '.env')
+        return null;
+    const instanceDir = path_1.default.dirname(normalized);
+    const instancesDir = path_1.default.dirname(instanceDir);
+    if (path_1.default.basename(instancesDir).toLowerCase() !== 'instances')
+        return null;
+    return path_1.default.dirname(instancesDir);
+}
+async function inspectProjectBinding(projectEnvFile) {
+    try {
+        const env = await readEnvFile(projectEnvFile);
+        const instanceEnvFile = env.IRANTI_INSTANCE_ENV?.trim() || null;
+        return {
+            bindingFile: projectEnvFile,
+            instanceEnvFile,
+            runtimeRoot: inferRuntimeRootFromInstanceEnv(instanceEnvFile ?? undefined),
+        };
+    }
+    catch {
+        return {
+            bindingFile: projectEnvFile,
+            instanceEnvFile: null,
+            runtimeRoot: null,
+        };
+    }
 }
 function getPackageVersion() {
     const pkgPath = path_1.default.join(packageRoot(), 'package.json');
@@ -345,10 +523,24 @@ async function writeJson(filePath, value) {
     await promises_1.default.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
 }
 async function writeText(filePath, content) {
-    await promises_1.default.writeFile(filePath, content, 'utf-8');
+    // Atomic write: write to temp file then rename to avoid partial writes on crash
+    const tmpPath = `${filePath}.tmp${process.pid}`;
+    try {
+        await promises_1.default.writeFile(tmpPath, content, { encoding: 'utf-8', flag: 'w' });
+        await promises_1.default.rename(tmpPath, filePath);
+    }
+    catch (err) {
+        await promises_1.default.unlink(tmpPath).catch(() => undefined);
+        throw err;
+    }
 }
+const MAX_ENV_FILE_BYTES = 1048576; // 1 MiB
 async function readEnvFile(filePath) {
     const out = {};
+    const stat = await promises_1.default.stat(filePath).catch(() => null);
+    if (stat && stat.size > MAX_ENV_FILE_BYTES) {
+        throw new Error(`Env file too large (${stat.size} bytes): ${filePath}. Maximum is ${MAX_ENV_FILE_BYTES} bytes.`);
+    }
     const raw = await promises_1.default.readFile(filePath, 'utf-8');
     for (const line of raw.split(/\r?\n/)) {
         const trimmed = line.trim();
@@ -448,9 +640,8 @@ async function upsertEnvFile(filePath, updates) {
     }
     const finalLines = nextLines
         .join('\n')
-        .replace(/\n{3,}/g, '\n\n')
-        .replace(/^\n+/, '')
-        .trimEnd();
+        .replace(/^\n+/, '') // strip leading blank lines only
+        .trimEnd(); // strip trailing whitespace only — preserving internal blank line groups
     await writeText(filePath, `${finalLines}\n`);
 }
 function redactSecret(value) {
@@ -469,44 +660,169 @@ function instancePaths(root, name) {
         runtimeFile: path_1.default.join(instanceDir, 'runtime.json'),
     };
 }
-async function loadInstanceEnv(root, name) {
+function instanceRepairNextSteps(name) {
+    return [
+        `Run \`iranti configure instance ${name} --interactive\` to repair the instance files.`,
+        'Run `iranti status --json` to inspect the current config classification.',
+    ];
+}
+async function loadInstanceEnv(root, name, options = {}) {
     const paths = instancePaths(root, name);
-    if (!fs_1.default.existsSync(paths.envFile)) {
+    const config = await inspectInstanceConfig(root, name);
+    if (!config.state.metaPresent && !config.state.envPresent) {
         throw cliError('IRANTI_INSTANCE_NOT_FOUND', `Instance '${name}' not found at ${paths.instanceDir}`, [
             'Run `iranti instance list` to see known instances.',
             `Run \`iranti setup\` or \`iranti instance create ${name}\` if this instance does not exist yet.`,
         ], { instance: name, root, instanceDir: paths.instanceDir });
     }
+    if (!options.allowRepair && config.classification !== 'complete') {
+        throw cliError(config.classification === 'partial' ? 'IRANTI_INSTANCE_INCOMPLETE' : 'IRANTI_INSTANCE_INVALID', `Instance '${name}' is ${config.classification}: ${config.detail}.`, instanceRepairNextSteps(name), {
+            instance: name,
+            root,
+            instanceDir: paths.instanceDir,
+            config: config.classification,
+            metaFile: paths.metaFile,
+            envFile: paths.envFile,
+        });
+    }
+    let env = {};
+    if (config.state.envPresent && config.state.envReadable) {
+        env = await readEnvFile(paths.envFile);
+    }
+    else if (!options.allowRepair) {
+        throw cliError('IRANTI_INSTANCE_ENV_UNREADABLE', `Instance '${name}' env file is missing or unreadable: ${paths.envFile}`, instanceRepairNextSteps(name), { instance: name, root, envFile: paths.envFile, config: config.classification });
+    }
     debugLog('Loaded instance env target.', { instance: name, envFile: paths.envFile });
     return {
         ...paths,
-        env: await readEnvFile(paths.envFile),
+        env,
+        config,
     };
 }
-async function readInstanceRuntimeSummary(root, name) {
-    const { runtimeFile } = instancePaths(root, name);
-    const state = await (0, runtimeLifecycle_1.readRuntimeState)(runtimeFile);
-    if (!state) {
-        return { state: null, running: false, stale: false };
+async function inspectInstanceConfig(root, name) {
+    const { instanceDir, envFile, metaFile } = instancePaths(root, name);
+    const metaPresent = fs_1.default.existsSync(metaFile);
+    const envPresent = fs_1.default.existsSync(envFile);
+    let metaReadable = false;
+    let envReadable = false;
+    const ownershipIssues = [];
+    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) {
+                if (parsed.name?.trim() !== name) {
+                    ownershipIssues.push(`instance.json name is ${parsed.name}`);
+                }
+                if (typeof parsed.instanceDir === 'string' && path_1.default.resolve(parsed.instanceDir) !== path_1.default.resolve(instanceDir)) {
+                    ownershipIssues.push(`instance.json points to ${parsed.instanceDir}`);
+                }
+                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}`);
+                }
+            }
+        }
+        catch {
+            metaReadable = false;
+        }
+    }
+    if (envPresent) {
+        try {
+            await readEnvFile(envFile);
+            envReadable = true;
+        }
+        catch {
+            envReadable = false;
+        }
+    }
+    let classification;
+    let detail;
+    if (ownershipIssues.length > 0) {
+        classification = 'invalid';
+        detail = ownershipIssues.join('; ');
+    }
+    else if (metaPresent && envPresent && metaReadable && envReadable) {
+        classification = 'complete';
+        detail = 'instance metadata and env are present';
+    }
+    else if ((metaPresent && !metaReadable) || (envPresent && !envReadable)) {
+        classification = 'invalid';
+        detail = [
+            !metaReadable && metaPresent ? 'instance metadata unreadable' : null,
+            !envReadable && envPresent ? 'env unreadable' : null,
+        ].filter((value) => Boolean(value)).join('; ');
+    }
+    else {
+        classification = 'partial';
+        detail = [
+            !metaPresent ? 'missing instance.json' : null,
+            !envPresent ? 'missing .env' : null,
+        ].filter((value) => Boolean(value)).join('; ') || 'instance directory incomplete';
     }
-    const running = (0, runtimeLifecycle_1.isPidRunning)(state.pid);
     return {
-        state,
-        running,
-        stale: !running && state.status !== 'stopped',
+        classification,
+        detail,
+        metaFile,
+        envFile,
+        state: {
+            metaPresent,
+            envPresent,
+            metaReadable,
+            envReadable,
+        },
     };
 }
+async function readInstanceRuntimeSummary(root, name) {
+    const { runtimeFile } = instancePaths(root, name);
+    return (0, runtimeLifecycle_1.inspectRuntimeState)(runtimeFile);
+}
 function describeInstanceRuntime(summary) {
-    if (!summary.state) {
-        return `${warnLabel('STOPPED')} no runtime metadata`;
+    switch (summary.classification) {
+        case 'running':
+            return `${okLabel('RUNNING')} ${summary.detail}`;
+        case 'unhealthy':
+            return `${failLabel('UNHEALTHY')} ${summary.detail}`;
+        case 'stale':
+            return `${warnLabel('STALE')} ${summary.detail}`;
+        case 'stopped':
+            return `${warnLabel('STOPPED')} ${summary.detail}`;
+        case 'invalid':
+            return `${failLabel('INVALID')} ${summary.detail}`;
+        case 'missing':
+        default:
+            return `${warnLabel('STOPPED')} ${summary.detail}`;
+    }
+}
+function describeInstanceConfig(summary) {
+    switch (summary.classification) {
+        case 'complete':
+            return `${okLabel('COMPLETE')} ${summary.detail}`;
+        case 'partial':
+            return `${warnLabel('PARTIAL')} ${summary.detail}`;
+        case 'invalid':
+        default:
+            return `${failLabel('INVALID')} ${summary.detail}`;
+    }
+}
+function buildInstanceRepairHints(name, config, runtime) {
+    const hints = [];
+    if (config.classification === 'partial') {
+        hints.push(`Run \`iranti configure instance ${name} --interactive\` to finish the missing instance files.`);
     }
-    if (summary.running) {
-        return `${okLabel('RUNNING')} pid=${summary.state.pid} version=${summary.state.version}`;
+    if (config.classification === 'invalid') {
+        hints.push(`Run \`iranti configure instance ${name} --interactive\` to repair invalid instance metadata or env values.`);
     }
-    if (summary.stale) {
-        return `${warnLabel('STALE')} last_pid=${summary.state.pid} version=${summary.state.version}`;
+    if (runtime.classification === 'stale') {
+        hints.push(`Run \`iranti instance restart ${name}\` if this instance should still be running.`);
     }
-    return `${warnLabel('STOPPED')} version=${summary.state.version}`;
+    if (runtime.classification === 'unhealthy') {
+        hints.push(`Run \`iranti doctor --instance ${name}\` and inspect ${runtime.state?.healthUrl ?? `http://localhost:${runtime.state?.port ?? 3001}/health`} before restarting.`);
+    }
+    if (runtime.classification === 'invalid') {
+        hints.push(`Inspect ${runtime.state?.runtimeFile ?? `instances/${name}/runtime.json`} for copied or foreign runtime metadata.`);
+    }
+    return Array.from(new Set(hints));
 }
 async function startInstanceRuntime(name, instanceDir, envFile, runtimeFile) {
     process.env.IRANTI_INSTANCE_NAME = name;
@@ -676,8 +992,9 @@ async function withPromptSession(run) {
         secret: async (prompt, currentValue) => {
             const placeholder = currentValue ? `${redactSecret(currentValue)} (enter new value to replace)` : 'leave blank to skip';
             const suffix = placeholder ? ` [${placeholder}]` : '';
+            process.stdout.write(`${prompt}${suffix}: `);
             muted = true;
-            const answer = (await rl.question(`${prompt}${suffix}: `)).trim();
+            const answer = (await rl.question('')).trim();
             muted = false;
             process.stdout.write('\n');
             if (!answer || answer === placeholder)
@@ -689,8 +1006,9 @@ async function withPromptSession(run) {
         secretRequired: async (prompt, currentValue) => {
             const placeholder = currentValue ? `${redactSecret(currentValue)} (enter new value to replace)` : 'required';
             const suffix = placeholder ? ` [${placeholder}]` : '';
+            process.stdout.write(`${prompt}${suffix}: `);
             muted = true;
-            const answer = (await rl.question(`${prompt}${suffix}: `)).trim();
+            const answer = (await rl.question('')).trim();
             muted = false;
             process.stdout.write('\n');
             if (!answer || answer === placeholder)
@@ -709,13 +1027,30 @@ function detectPlaceholder(value) {
     if (!value)
         return true;
     const normalized = value.trim().toLowerCase();
-    return normalized.length === 0
-        || normalized.includes('yourpassword')
-        || normalized.includes('replace_me')
-        || normalized.includes('your_secret')
-        || normalized.includes('your_key_here')
-        || normalized.includes('your_api_key')
-        || normalized === 'changeme';
+    if (normalized.length === 0)
+        return true;
+    const exactWeakValues = new Set([
+        'changeme',
+        'placeholder',
+        'example',
+        'todo',
+        'fixme',
+        'none',
+        'null',
+        'undefined',
+    ]);
+    if (exactWeakValues.has(normalized))
+        return true;
+    const weakFragments = [
+        'yourpassword',
+        'replace_me',
+        'your_secret',
+        'your_key_here',
+        'your_api_key',
+        'insert_key_here',
+        'add_your_key',
+    ];
+    return weakFragments.some((p) => normalized.includes(p));
 }
 function quoteSqlLiteral(value) {
     return `'${value.replace(/'/g, "''")}'`;
@@ -750,6 +1085,9 @@ function isLocalPostgresHost(hostname) {
 }
 function sanitizeIdentifier(input, fallback) {
     const value = input.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+    if (!value && input.trim()) {
+        verboseLog(`sanitizeIdentifier: input "${input}" normalized to empty — using fallback "${fallback}"`);
+    }
     return value || fallback;
 }
 function projectAgentDefault(projectPath) {
@@ -840,6 +1178,18 @@ async function promptRequiredSecret(session, prompt, currentValue) {
         console.log(`${warnLabel()} ${prompt} is required.`);
     }
 }
+async function promptSecretWithDefault(session, prompt, defaultValue) {
+    while (true) {
+        const value = (await session.secret(`${prompt} (blank uses local-dev default)`, undefined) ?? '').trim();
+        if (!value) {
+            console.log(`${infoLabel()} Using the local development default for ${prompt}.`);
+            return defaultValue;
+        }
+        if (!detectPlaceholder(value))
+            return value;
+        console.log(`${warnLabel()} ${prompt} still looks like a placeholder. Enter a real value or leave it blank to use the local-dev default.`);
+    }
+}
 function makeLegacyInstanceApiKey(instanceName) {
     const keyId = sanitizeIdentifier(`${instanceName}_${os_1.default.userInfo().username}`, 'iranti');
     return (0, apiKeys_1.formatApiKeyToken)(keyId, (0, apiKeys_1.generateApiKeySecret)());
@@ -883,6 +1233,7 @@ async function ensureInstanceConfigured(root, name, config) {
         LLM_PROVIDER: config.provider,
         ...config.providerKeys,
     });
+    await syncInstanceMeta(root, name, config.port);
     return { envFile, instanceDir, created };
 }
 function makeIrantiMcpServerConfig() {
@@ -990,6 +1341,76 @@ function resolveAttendMessage(args) {
         return fromPositionals;
     throw new Error('Missing latest message. Usage: iranti attend [message] [--message <text>] [--context <text>] [--json]');
 }
+function parseDelimitedList(raw) {
+    if (!raw?.trim())
+        return [];
+    const delimiter = raw.includes('||') ? '||' : ',';
+    return raw
+        .split(delimiter)
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function resolveTaskEntity(args) {
+    const entity = (args.subcommand ?? args.positionals[0] ?? getFlag(args, 'entity') ?? '').trim();
+    if (!entity) {
+        throw new Error('Missing task entity. Usage: iranti handoff task/<task_id> --next-step <text> [--json]');
+    }
+    if (!entity.includes('/')) {
+        throw new Error('task entity must use entityType/entityId format.');
+    }
+    return entity;
+}
+function buildHandoffSummary(key, value) {
+    switch (key) {
+        case 'status': {
+            const state = typeof value === 'object' && value && 'state' in value ? String(value.state) : 'updated';
+            return `Shared task status is ${state}.`;
+        }
+        case 'current_owner': {
+            const agentId = typeof value === 'object' && value && 'agentId' in value ? String(value.agentId) : 'unassigned';
+            return `Current owner is ${agentId}.`;
+        }
+        case 'next_step': {
+            const instruction = typeof value === 'object' && value && 'instruction' in value ? String(value.instruction) : 'Next step updated.';
+            return truncateText(`Next step: ${instruction}`, 140);
+        }
+        case 'blockers': {
+            const count = typeof value === 'object' && value && 'items' in value && Array.isArray(value.items)
+                ? value.items.length
+                : 0;
+            return count === 0 ? 'No blockers recorded.' : `${count} blocker${count === 1 ? '' : 's'} recorded for the shared task.`;
+        }
+        case 'artifacts': {
+            const count = typeof value === 'object' && value && 'files' in value && Array.isArray(value.files)
+                ? value.files.length
+                : 0;
+            return count === 0 ? 'No artifacts recorded.' : `${count} artifact${count === 1 ? '' : 's'} recorded for the shared task.`;
+        }
+        case 'notes': {
+            const text = typeof value === 'object' && value && 'text' in value ? String(value.text) : 'Shared handoff notes updated.';
+            return truncateText(`Notes: ${text}`, 140);
+        }
+        case 'active_handoff_task': {
+            const taskEntity = typeof value === 'object' && value && 'taskEntity' in value ? String(value.taskEntity) : 'task';
+            return `Project now points to active handoff ${taskEntity}.`;
+        }
+        default:
+            return 'Shared handoff state updated.';
+    }
+}
+function printHandoffResult(target, taskEntity, writes) {
+    console.log(bold('Iranti handoff'));
+    console.log(`  agent         ${target.agentId}`);
+    console.log(`  env source    ${target.envSource}`);
+    if (target.envFile)
+        console.log(`  env file      ${target.envFile}`);
+    console.log(`  task entity   ${taskEntity}`);
+    console.log(`  writes        ${writes.length}`);
+    console.log('');
+    for (const write of writes) {
+        console.log(`- ${write.entity} :: ${write.key} | ${write.summary}`);
+    }
+}
 function printHandshakeResult(target, task, result) {
     console.log(bold('Iranti handshake'));
     console.log(`  agent         ${target.agentId}`);
@@ -1220,7 +1641,7 @@ function inspectDockerAvailability() {
         detail: `Docker CLI is installed, but the daemon is not reachable. ${reason}`,
     };
 }
-async function isPortAvailable(port, host = '127.0.0.1') {
+async function isPortAvailable(port, host = '0.0.0.0') {
     return await new Promise((resolve) => {
         const server = net_1.default.createServer();
         server.unref();
@@ -1230,18 +1651,58 @@ async function isPortAvailable(port, host = '127.0.0.1') {
         });
     });
 }
-async function findNextAvailablePort(start, host = '127.0.0.1', maxSteps = 50) {
+function listPublishedDockerHostPorts() {
+    const docker = inspectDockerAvailability();
+    if (!docker.daemonReachable)
+        return new Set();
+    const inspect = runCommandCapture('docker', ['ps', '--format', '{{.Ports}}']);
+    if (inspect.status !== 0)
+        return new Set();
+    return (0, dockerCliParsing_1.parsePublishedDockerHostPorts)(inspect.stdout ?? '');
+}
+async function isPortUsable(port, host = '0.0.0.0', dockerPublishedPorts = new Set()) {
+    if (dockerPublishedPorts.has(port))
+        return false;
+    return isPortAvailable(port, host);
+}
+async function findNextAvailablePort(start, host = '0.0.0.0', maxSteps = 50, dockerPublishedPorts = new Set()) {
     for (let port = start; port < start + maxSteps; port += 1) {
-        if (await isPortAvailable(port, host)) {
+        if (await isPortUsable(port, host, dockerPublishedPorts)) {
             return port;
         }
     }
     throw new Error(`No available port found in range ${start}-${start + maxSteps - 1}.`);
 }
-async function chooseAvailablePort(session, promptText, preferredPort, allowOccupiedCurrent = false) {
+async function readAllInstancePorts(root) {
+    const ports = new Set();
+    const instancesDir = path_1.default.join(root, 'instances');
+    if (!fs_1.default.existsSync(instancesDir))
+        return ports;
+    try {
+        const entries = await promises_1.default.readdir(instancesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const metaPath = path_1.default.join(instancesDir, entry.name, 'instance.json');
+            try {
+                const raw = await promises_1.default.readFile(metaPath, 'utf-8');
+                const meta = JSON.parse(raw);
+                const port = Number(meta.port);
+                if (Number.isFinite(port) && port > 0)
+                    ports.add(port);
+            }
+            catch { /* ignore unreadable meta files */ }
+        }
+    }
+    catch { /* ignore unreadable instances dir */ }
+    return ports;
+}
+async function chooseAvailablePort(session, promptText, preferredPort, allowOccupiedCurrent = false, reservedPorts = new Set()) {
+    const dockerPublishedPorts = listPublishedDockerHostPorts();
+    const allReserved = new Set([...dockerPublishedPorts, ...reservedPorts]);
     let suggested = preferredPort;
-    if (!allowOccupiedCurrent && !(await isPortAvailable(preferredPort))) {
-        suggested = await findNextAvailablePort(preferredPort + 1);
+    if (!allowOccupiedCurrent && !(await isPortUsable(preferredPort, '0.0.0.0', allReserved))) {
+        suggested = await findNextAvailablePort(preferredPort + 1, '0.0.0.0', 50, allReserved);
         console.log(`${warnLabel()} Port ${preferredPort} is already in use. A good next option is ${suggested}.`);
     }
     while (true) {
@@ -1254,14 +1715,66 @@ async function chooseAvailablePort(session, promptText, preferredPort, allowOccu
         if (allowOccupiedCurrent && parsed === preferredPort) {
             return parsed;
         }
-        if (await isPortAvailable(parsed)) {
+        if (await isPortUsable(parsed, '0.0.0.0', allReserved)) {
             return parsed;
         }
-        const next = await findNextAvailablePort(parsed + 1);
+        const next = await findNextAvailablePort(parsed + 1, '0.0.0.0', 50, allReserved);
         console.log(`${warnLabel()} Port ${parsed} is already in use. Try ${next} instead.`);
         suggested = next;
     }
 }
+async function syncInstanceMeta(root, name, port) {
+    const { instanceDir, envFile, metaFile } = instancePaths(root, name);
+    const existingCreatedAt = fs_1.default.existsSync(metaFile)
+        ? await promises_1.default.readFile(metaFile, 'utf-8')
+            .then((raw) => {
+            try {
+                const parsed = JSON.parse(raw);
+                return typeof parsed.createdAt === 'string' ? parsed.createdAt : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })
+        : undefined;
+    const meta = {
+        name,
+        createdAt: existingCreatedAt ?? new Date().toISOString(),
+        port,
+        envFile,
+        instanceDir,
+    };
+    await writeJson(metaFile, meta);
+}
+async function assertPortAssignable(root, port, currentInstanceName) {
+    const reservedPorts = await readAllInstancePorts(root);
+    let allowCurrentRunningPort = false;
+    if (currentInstanceName) {
+        const { envFile } = instancePaths(root, currentInstanceName);
+        if (fs_1.default.existsSync(envFile)) {
+            try {
+                const env = await readEnvFile(envFile);
+                const currentPort = Number.parseInt(env.IRANTI_PORT ?? '', 10);
+                if (Number.isFinite(currentPort) && currentPort > 0) {
+                    reservedPorts.delete(currentPort);
+                    if (currentPort === port) {
+                        const runtime = await readInstanceRuntimeSummary(root, currentInstanceName);
+                        allowCurrentRunningPort = runtime.running && runtime.state?.port === port;
+                    }
+                }
+            }
+            catch {
+                // Ignore unreadable current instance env and fall back to stricter validation.
+            }
+        }
+    }
+    if (reservedPorts.has(port)) {
+        throw new Error(`Port ${port} is already assigned to another Iranti instance.`);
+    }
+    if (!allowCurrentRunningPort && !(await isPortUsable(port, '0.0.0.0', listPublishedDockerHostPorts()))) {
+        throw new Error(`Port ${port} is already in use.`);
+    }
+}
 async function waitForTcpPort(host, port, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -1290,16 +1803,14 @@ async function runDockerPostgresContainer(options) {
     if (!docker.daemonReachable) {
         throw new Error(`Docker daemon is not reachable. Start Docker Desktop or Docker Engine, then retry. ${docker.detail}`);
     }
-    const inspect = process.platform === 'win32'
-        ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', `docker ps -a --format "{{.Names}}"`], { encoding: 'utf8' })
-        : (0, child_process_1.spawnSync)('docker', ['ps', '-a', '--format', '{{.Names}}'], { encoding: 'utf8' });
+    const inspect = runCommandCapture('docker', ['ps', '-a', '--format', '{{.Names}}']);
     if (inspect.status !== 0) {
         throw new Error(`Failed to inspect Docker containers. ${(inspect.stderr ?? inspect.stdout ?? '').trim() || 'docker ps returned a non-zero exit code.'}`);
     }
-    const names = (inspect.stdout ?? '').split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+    const names = (0, dockerCliParsing_1.parseDockerContainerNames)(inspect.stdout ?? '');
     if (names.includes(options.containerName)) {
         const start = process.platform === 'win32'
-            ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', `docker start ${options.containerName}`], { stdio: 'inherit' })
+            ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', ['docker', 'start', options.containerName].map(quoteForCmd).join(' ')], { stdio: 'inherit' })
             : (0, child_process_1.spawnSync)('docker', ['start', options.containerName], { stdio: 'inherit' });
         if (start.status !== 0) {
             throw new Error(`Failed to start existing Docker container '${options.containerName}'.`);
@@ -1800,9 +2311,12 @@ function printDependencyChecks(checks) {
 function quoteForCmd(arg) {
     if (arg.length === 0)
         return '""';
-    if (!/[ \t"&()<>|^]/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '\\"')}"`;
+    // Escape % to prevent CMD variable expansion (%VAR%)
+    const pctEscaped = arg.replace(/%/g, '%%');
+    if (!/[ \t"&()<>|^%!]/.test(arg))
+        return pctEscaped;
+    // Use "" for inner double quotes (CMD convention, not Unix \")
+    return `"${pctEscaped.replace(/"/g, '""')}"`;
 }
 function runCommandCapture(executable, args, cwd, extraEnv) {
     verboseLog('Running subprocess (capture).', {
@@ -1895,7 +2409,11 @@ function spawnDetachedCli(args, cwd) {
         env: process.env,
     });
     child.unref();
-    return child.pid ?? 0;
+    const pid = child.pid;
+    if (!pid) {
+        throw new Error(`Failed to spawn detached CLI process (executable: ${invocation.executable}). The process did not start.`);
+    }
+    return pid;
 }
 async function restartInstanceRuntime(args, instanceName, scope, root) {
     const runtimeBefore = await readInstanceRuntimeSummary(root, instanceName);
@@ -2103,14 +2621,20 @@ function readJsonFile(filePath) {
         return null;
     }
 }
-function httpsJson(url, headers = {}) {
+function httpsJson(url, headers = {}, _redirectDepth = 0) {
+    const MAX_REDIRECTS = 5;
+    const REQUEST_TIMEOUT_MS = 10000;
     return new Promise((resolve, reject) => {
         const request = https_1.default.get(url, { headers }, (response) => {
             const statusCode = response.statusCode ?? 0;
             if (statusCode >= 300 && statusCode < 400 && response.headers.location) {
                 response.resume();
+                if (_redirectDepth >= MAX_REDIRECTS) {
+                    reject(new Error(`Too many redirects fetching ${url}`));
+                    return;
+                }
                 const redirect = new URL(response.headers.location, url).toString();
-                httpsJson(redirect, headers).then(resolve).catch(reject);
+                httpsJson(redirect, headers, _redirectDepth + 1).then(resolve).catch(reject);
                 return;
             }
             if (statusCode < 200 || statusCode >= 300) {
@@ -2132,7 +2656,7 @@ function httpsJson(url, headers = {}) {
                 }
             });
         });
-        request.setTimeout(5000, () => {
+        request.setTimeout(REQUEST_TIMEOUT_MS, () => {
             request.destroy(new Error(`Timed out fetching ${url}`));
         });
         request.on('error', reject);
@@ -2371,6 +2895,10 @@ function escapeForSingleQuotedPowerShell(value) {
     return value.replace(/'/g, "''");
 }
 function resolveWindowsDetachedExecutable(executable) {
+    // H-5: Validate executable name — reject empty strings or strings with shell metacharacters
+    if (!executable || /[;&|<>\n\r`$(){}[\]\\/"']/.test(executable)) {
+        throw new Error(`Invalid executable name: "${executable}"`);
+    }
     if (path_1.default.isAbsolute(executable)) {
         return executable;
     }
@@ -2427,7 +2955,19 @@ function launchDetachedWindowsPowerShellFile(scriptPath, cwd) {
         throw new Error(`Failed to schedule detached PowerShell handoff. ${(proc.stderr || proc.stdout).trim() || 'powershell returned a non-zero exit code.'}`);
     }
 }
+// C-5: postCommand must be a pre-escaped PowerShell snippet produced internally (never from raw user input).
+// Validate it against a strict allowlist pattern to prevent future injection if the call site changes.
+function validateDetachedPostCommand(postCommand) {
+    // Allow only: alphanumeric, spaces, single-quotes, hyphens, underscores, dots, slashes,
+    // backslashes, colons, and & for PS call operator.
+    if (!/^[a-zA-Z0-9 '&_\-./:\\]+$/.test(postCommand)) {
+        throw new Error(`Unsafe characters in detached post-command. Only pre-escaped PowerShell call expressions are permitted.`);
+    }
+}
 function scheduleDetachedWindowsGlobalNpmUpgrade(command, postCommand) {
+    if (postCommand !== undefined) {
+        validateDetachedPostCommand(postCommand);
+    }
     const neutralCwd = resolveDetachedUpgradeCwd(command);
     const parentPid = process.pid;
     const escapedCwd = escapeForSingleQuotedPowerShell(neutralCwd);
@@ -3322,7 +3862,11 @@ async function setupCommand(args) {
             console.log(`${infoLabel()} Creating new instance '${instanceName}'.`);
         }
         const existingPort = Number.parseInt(existingInstance?.env.IRANTI_PORT ?? '3001', 10);
-        const port = await chooseAvailablePort(prompt, 'API port', existingPort, Boolean(existingInstance));
+        const existingInstancePorts = await readAllInstancePorts(finalRoot);
+        // Exclude the current instance's own port from the reserved set when updating
+        if (existingInstance)
+            existingInstancePorts.delete(existingPort);
+        const port = await chooseAvailablePort(prompt, 'API port', existingPort, Boolean(existingInstance), existingInstancePorts);
         const dockerStatus = inspectDockerAvailability();
         const dockerAvailable = dockerStatus.daemonReachable;
         const psqlAvailable = hasCommandInstalled('psql');
@@ -3364,7 +3908,7 @@ async function setupCommand(args) {
                 }
                 const dbHostPort = await chooseAvailablePort(prompt, 'Docker PostgreSQL host port', 5432, false);
                 const dbName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker PostgreSQL database name', `iranti_${instanceName}`), `iranti_${instanceName}`);
-                const dbPassword = await promptRequiredSecret(prompt, 'Docker PostgreSQL password');
+                const dbPassword = await promptSecretWithDefault(prompt, 'Docker PostgreSQL password', 'postgres');
                 const containerName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker container name', `iranti_${instanceName}_db`), `iranti_${instanceName}_db`);
                 dockerContainerName = containerName;
                 dbUrl = `postgresql://postgres:${dbPassword}@localhost:${dbHostPort}/${dbName}`;
@@ -3742,51 +4286,67 @@ async function doctorCommand(args) {
 }
 async function statusCommand(args) {
     const scope = normalizeScope(getFlag(args, 'scope'));
-    const root = resolveInstallRoot(args, scope);
+    const resolution = resolveInstallRootDetails(args, scope);
+    const root = resolution.root;
     const json = hasFlag(args, 'json');
     const cwd = process.cwd();
-    const repoEnv = path_1.default.join(cwd, '.env');
-    const projectEnv = path_1.default.join(cwd, '.env.iranti');
-    const installMetaPath = path_1.default.join(root, 'install.json');
-    const instancesDir = path_1.default.join(root, 'instances');
+    const repoEnv = findClosestAncestorFile(cwd, '.env');
+    const projectEnv = findClosestAncestorFile(cwd, '.env.iranti');
+    const localRuntimeRoot = findClosestAncestorRuntimeRoot(cwd);
+    const installMetaPath = resolution.installMetaPath;
+    const binding = projectEnv && fs_1.default.existsSync(projectEnv) ? await inspectProjectBinding(projectEnv) : null;
+    const boundRuntimeRoot = binding?.runtimeRoot ?? null;
+    const boundInstanceEnv = binding?.instanceEnvFile ?? null;
+    const rootMismatch = Boolean(boundRuntimeRoot && path_1.default.resolve(boundRuntimeRoot) !== path_1.default.resolve(root));
+    const userInstallRuntimeRoot = fs_1.default.existsSync(path_1.default.join(resolution.userRoot, 'install.json')) ? resolution.userRoot : null;
+    const systemInstallRuntimeRoot = fs_1.default.existsSync(path_1.default.join(resolution.systemRoot, 'install.json')) ? resolution.systemRoot : null;
+    const otherRuntimeRoots = Array.from(new Set([boundRuntimeRoot, localRuntimeRoot]
+        .filter((candidate) => Boolean(candidate))
+        .map((candidate) => path_1.default.resolve(candidate))
+        .filter((candidate) => candidate !== path_1.default.resolve(root) && fs_1.default.existsSync(candidate))));
     const rows = [];
     rows.push({ label: 'version', value: getPackageVersion() });
     rows.push({ label: 'scope', value: scope });
     rows.push({ label: 'runtime_root', value: root });
-    rows.push({ label: 'repo_env', value: fs_1.default.existsSync(repoEnv) ? repoEnv : '(missing)' });
-    rows.push({ label: 'project_binding', value: fs_1.default.existsSync(projectEnv) ? projectEnv : '(missing)' });
+    rows.push({ label: 'root_source', value: describeRuntimeRootSource(resolution.source) });
+    if (boundRuntimeRoot)
+        rows.push({ label: 'bound_root', value: boundRuntimeRoot });
+    rows.push({ label: 'repo_env', value: repoEnv && fs_1.default.existsSync(repoEnv) ? repoEnv : '(missing)' });
+    rows.push({ label: 'project_binding', value: projectEnv && fs_1.default.existsSync(projectEnv) ? projectEnv : '(missing)' });
     rows.push({ label: 'install_meta', value: fs_1.default.existsSync(installMetaPath) ? installMetaPath : '(not initialized)' });
-    const instances = [];
-    if (fs_1.default.existsSync(instancesDir)) {
-        const entries = await promises_1.default.readdir(instancesDir, { withFileTypes: true });
-        for (const entry of entries.filter((value) => value.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
-            const envFile = path_1.default.join(instancesDir, entry.name, '.env');
-            let port = '(unknown)';
-            if (fs_1.default.existsSync(envFile)) {
-                try {
-                    const env = await readEnvFile(envFile);
-                    port = env.IRANTI_PORT ?? '(unknown)';
-                }
-                catch {
-                    port = '(unreadable)';
-                }
-            }
-            instances.push({
-                name: entry.name,
-                port,
-                envFile: fs_1.default.existsSync(envFile) ? envFile : '(missing)',
-                runtime: await readInstanceRuntimeSummary(root, entry.name),
-            });
-        }
-    }
+    if (rootMismatch)
+        rows.push({ label: 'root_mismatch', value: 'project binding points at a different runtime root' });
+    const instances = await collectRuntimeInstanceSummaries(root);
+    const recommendedActions = Array.from(new Set(instances.flatMap((instance) => instance.repairHints)));
     if (json) {
         console.log(JSON.stringify({
             version: getPackageVersion(),
             scope,
             runtimeRoot: root,
-            repoEnv: fs_1.default.existsSync(repoEnv) ? repoEnv : null,
-            projectBinding: fs_1.default.existsSync(projectEnv) ? projectEnv : null,
+            runtimeRootSource: resolution.source,
+            discovery: {
+                selectedRuntimeRoot: root,
+                selectionSource: resolution.source,
+                selectionReason: describeRuntimeRootSource(resolution.source),
+                boundRuntimeRoot,
+                boundInstanceEnv,
+                ancestorRuntimeRoot: localRuntimeRoot,
+                userInstallRuntimeRoot,
+                systemInstallRuntimeRoot,
+                projectBindingFile: projectEnv && fs_1.default.existsSync(projectEnv) ? projectEnv : null,
+                projectBindingSource: projectEnv && fs_1.default.existsSync(projectEnv) ? 'ancestor-project-binding' : null,
+                repoEnvFile: repoEnv && fs_1.default.existsSync(repoEnv) ? repoEnv : null,
+                rootMismatch,
+                otherRuntimeRoots,
+            },
+            boundRuntimeRoot,
+            boundInstanceEnv,
+            rootMismatch,
+            otherRuntimeRoots,
+            repoEnv: repoEnv && fs_1.default.existsSync(repoEnv) ? repoEnv : null,
+            projectBinding: projectEnv && fs_1.default.existsSync(projectEnv) ? projectEnv : null,
             installMeta: fs_1.default.existsSync(installMetaPath) ? installMetaPath : null,
+            recommendedActions,
             instances,
         }, null, 2));
         return;
@@ -3795,6 +4355,12 @@ async function statusCommand(args) {
     for (const row of rows) {
         console.log(`  ${row.label.padEnd(15)} ${row.value}`);
     }
+    if (otherRuntimeRoots.length > 0) {
+        console.log('  other_roots');
+        for (const runtimeRoot of otherRuntimeRoots) {
+            console.log(`    - ${runtimeRoot}`);
+        }
+    }
     console.log('');
     if (instances.length === 0) {
         console.log('Instances: none');
@@ -3804,17 +4370,24 @@ async function statusCommand(args) {
         for (const instance of instances) {
             console.log(`  - ${instance.name} (port ${instance.port})`);
             console.log(`    env: ${instance.envFile}`);
-            if (instance.runtime.state) {
-                const runtimeLabel = instance.runtime.running
-                    ? `${okLabel('RUNNING')} pid=${instance.runtime.state.pid} version=${instance.runtime.state.version}`
-                    : instance.runtime.stale
-                        ? `${warnLabel('STALE')} last_pid=${instance.runtime.state.pid} version=${instance.runtime.state.version}`
-                        : `${warnLabel('STOPPED')} version=${instance.runtime.state.version}`;
-                console.log(`    runtime: ${runtimeLabel}`);
+            console.log(`    meta: ${instance.metaFile}`);
+            console.log(`    config: ${describeInstanceConfig(instance.config)}`);
+            console.log(`    runtime: ${describeInstanceRuntime(instance.runtime)}`);
+            if (instance.repairHints.length > 0) {
+                console.log('    hints:');
+                for (const hint of instance.repairHints) {
+                    console.log(`      - ${hint}`);
+                }
+            }
+            if (instance.runtime.state?.healthUrl) {
                 console.log(`    health: ${instance.runtime.state.healthUrl}`);
             }
-            else {
-                console.log(`    runtime: ${warnLabel('STOPPED')} no runtime metadata`);
+        }
+        if (recommendedActions.length > 0) {
+            console.log('');
+            console.log('Suggested fixes:');
+            for (const action of recommendedActions) {
+                console.log(`  - ${action}`);
             }
         }
     }
@@ -3827,9 +4400,10 @@ async function collectRuntimeInstanceSummaries(root) {
     }
     const entries = await promises_1.default.readdir(instancesDir, { withFileTypes: true });
     for (const entry of entries.filter((value) => value.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
-        const envFile = path_1.default.join(instancesDir, entry.name, '.env');
+        const { envFile, metaFile } = instancePaths(root, entry.name);
+        const config = await inspectInstanceConfig(root, entry.name);
         let port = '(unknown)';
-        if (fs_1.default.existsSync(envFile)) {
+        if (config.state.envPresent && config.state.envReadable) {
             try {
                 const env = await readEnvFile(envFile);
                 port = env.IRANTI_PORT ?? '(unknown)';
@@ -3838,11 +4412,15 @@ async function collectRuntimeInstanceSummaries(root) {
                 port = '(unreadable)';
             }
         }
+        const runtime = await readInstanceRuntimeSummary(root, entry.name);
         instances.push({
             name: entry.name,
             port,
-            envFile: fs_1.default.existsSync(envFile) ? envFile : '(missing)',
-            runtime: await readInstanceRuntimeSummary(root, entry.name),
+            envFile: config.state.envPresent ? envFile : '(missing)',
+            metaFile: config.state.metaPresent ? metaFile : '(missing)',
+            config,
+            runtime,
+            repairHints: buildInstanceRepairHints(entry.name, config, runtime),
         });
     }
     return instances;
@@ -4108,9 +4686,20 @@ async function createInstanceCommand(args) {
         throw new Error(`Provider '${provider}' does not use a remote API key.`);
     }
     const { instanceDir, envFile, metaFile } = instancePaths(root, name);
-    if (fs_1.default.existsSync(instanceDir) && !hasFlag(args, 'force')) {
+    const instanceAlreadyExisted = fs_1.default.existsSync(instanceDir);
+    if (instanceAlreadyExisted && !hasFlag(args, 'force')) {
         throw new Error(`Instance '${name}' already exists at ${instanceDir}. Use --force to overwrite.`);
     }
+    await assertPortAssignable(root, port, instanceAlreadyExisted ? name : undefined);
+    // H-7: Register rollback if the instance dir is new (so SIGINT cleans up partial state)
+    if (!instanceAlreadyExisted) {
+        pushCleanup(async () => {
+            try {
+                await promises_1.default.rm(instanceDir, { recursive: true, force: true });
+            }
+            catch { }
+        });
+    }
     await ensureDir(instanceDir);
     await ensureDir(path_1.default.join(instanceDir, 'logs'));
     await ensureDir(path_1.default.join(instanceDir, 'escalation', 'active'));
@@ -4129,6 +4718,9 @@ async function createInstanceCommand(args) {
         instanceDir,
     };
     await writeJson(metaFile, meta);
+    // Instance fully created — pop the rollback so it doesn't run on normal exit
+    if (!instanceAlreadyExisted)
+        popCleanup();
     console.log(sectionTitle('Instance Created'));
     console.log(`  status  ${okLabel()}`);
     console.log(`  dir : ${instanceDir}`);
@@ -4183,15 +4775,18 @@ async function showInstanceCommand(args) {
         throw new Error('Missing instance name. Usage: iranti instance show <name>');
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
-    const instanceDir = path_1.default.join(root, 'instances', name);
-    const envFile = path_1.default.join(instanceDir, '.env');
-    if (!fs_1.default.existsSync(envFile))
+    const { instanceDir, envFile } = instancePaths(root, name);
+    const config = await inspectInstanceConfig(root, name);
+    if (!config.state.metaPresent && !config.state.envPresent)
         throw new Error(`Instance '${name}' not found at ${instanceDir}`);
-    const env = await readEnvFile(envFile);
+    const env = config.state.envPresent && config.state.envReadable
+        ? await readEnvFile(envFile)
+        : {};
     const runtime = await readInstanceRuntimeSummary(root, name);
     console.log(bold(`Instance: ${name}`));
     console.log(`  dir : ${instanceDir}`);
     console.log(`  env : ${envFile}`);
+    console.log(`  config: ${describeInstanceConfig(config)}`);
     console.log(`  port: ${env.IRANTI_PORT ?? '3001'}`);
     console.log(`  db  : ${env.DATABASE_URL ?? '(missing)'}`);
     console.log(`  esc : ${env.IRANTI_ESCALATION_DIR ?? '(missing)'}`);
@@ -4208,11 +4803,7 @@ async function runInstanceCommand(args) {
     }
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
-    const { instanceDir, envFile, runtimeFile } = instancePaths(root, name);
-    if (!fs_1.default.existsSync(envFile)) {
-        throw cliError('IRANTI_INSTANCE_NOT_FOUND', `Instance '${name}' not found. Create it first.`, [`Run \`iranti setup\` or \`iranti instance create ${name}\` first.`], { instance: name, envFile });
-    }
-    const env = await readEnvFile(envFile);
+    const { instanceDir, envFile, runtimeFile, env } = await loadInstanceEnv(root, name);
     const runtime = await readInstanceRuntimeSummary(root, name);
     if (runtime.running) {
         throw cliError('IRANTI_INSTANCE_ALREADY_RUNNING', `Instance '${name}' is already running on pid ${runtime.state?.pid ?? '(unknown)'}.`, [`Run \`iranti instance restart ${name}\` to restart the live process, or stop the existing process first.`], { instance: name, pid: runtime.state?.pid ?? null, runtimeFile });
@@ -4226,6 +4817,13 @@ async function runInstanceCommand(args) {
     if (!process.env.DATABASE_URL || process.env.DATABASE_URL.includes('yourpassword')) {
         throw cliError('IRANTI_INSTANCE_DATABASE_PLACEHOLDER', `Instance '${name}' has placeholder DATABASE_URL. Edit ${envFile} first.`, ['Run `iranti configure instance <name> --interactive` or rerun `iranti setup`.'], { instance: name, envFile });
     }
+    const port = Number.parseInt(env.IRANTI_PORT ?? '3001', 10);
+    if (!Number.isFinite(port) || port <= 0) {
+        throw cliError('IRANTI_INSTANCE_PORT_INVALID', `Instance '${name}' has invalid IRANTI_PORT in ${envFile}.`, ['Run `iranti configure instance <name> --port <n>` to repair it.'], { instance: name, envFile, port: env.IRANTI_PORT ?? null });
+    }
+    if (!(await isPortUsable(port, '0.0.0.0', listPublishedDockerHostPorts()))) {
+        throw cliError('IRANTI_INSTANCE_PORT_IN_USE', `Cannot start instance '${name}' because port ${port} is already in use.`, ['Run `iranti configure instance <name> --port <n>` or free the port before retrying.'], { instance: name, envFile, port });
+    }
     await startInstanceRuntime(name, instanceDir, envFile, runtimeFile);
 }
 async function restartInstanceCommand(args) {
@@ -4293,7 +4891,7 @@ async function configureInstanceCommand(args) {
     }
     const scope = normalizeScope(getFlag(args, 'scope'));
     const root = resolveInstallRoot(args, scope);
-    const { envFile, env } = await loadInstanceEnv(root, name);
+    const { instanceDir, envFile, env, config } = await loadInstanceEnv(root, name, { allowRepair: true });
     const updates = {};
     let portRaw = getFlag(args, 'port');
     let dbUrl = getFlag(args, 'db-url');
@@ -4319,6 +4917,7 @@ async function configureInstanceCommand(args) {
         const port = Number.parseInt(portRaw, 10);
         if (!Number.isFinite(port) || port <= 0)
             throw new Error(`Invalid --port '${portRaw}'.`);
+        await assertPortAssignable(root, port, name);
         updates.IRANTI_PORT = String(port);
     }
     if (dbUrl)
@@ -4345,7 +4944,26 @@ async function configureInstanceCommand(args) {
     if (Object.keys(updates).length === 0) {
         throw new Error('No changes provided. Use flags like --provider, --provider-key, --api-key, --db-url, or --port.');
     }
+    const nextEnv = { ...env };
+    for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined) {
+            delete nextEnv[key];
+        }
+        else {
+            nextEnv[key] = value;
+        }
+    }
+    const nextPortRaw = nextEnv.IRANTI_PORT?.trim();
+    const nextPort = Number.parseInt(nextPortRaw ?? '', 10);
+    if (!Number.isFinite(nextPort) || nextPort <= 0) {
+        throw cliError('IRANTI_INSTANCE_PORT_REQUIRED', `Instance '${name}' still needs a valid IRANTI_PORT before it can be considered repaired.`, ['Pass `--port <n>` or rerun `iranti configure instance <name> --interactive`.'], { instance: name, envFile, port: nextPortRaw ?? null, config: config.classification });
+    }
+    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 });
+    }
+    await ensureDir(instanceDir);
     await upsertEnvFile(envFile, updates);
+    await syncInstanceMeta(root, name, nextPort);
     const json = hasFlag(args, 'json');
     const result = {
         instance: name,
@@ -4638,6 +5256,113 @@ async function attendCommand(args) {
     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 }),
+        });
+    }
+    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));
+        process.exit(0);
+    }
+    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([
         'Scaffold Claude Code MCP and hook files for the current project.',
@@ -4930,12 +5655,14 @@ function printHelp() {
         ['iranti remove api-key [provider] [--instance <name>] [--project <path>] [--json]', 'Remove a stored provider key.'],
     ]);
     printRows('Diagnostics And Operator Tools', [
+        ['iranti version', 'Print the installed CLI version and exit.'],
         ['iranti doctor [--instance <name>] [--scope user|system] [--env <file>] [--json] [--debug]', 'Run environment and runtime diagnostics.'],
         ['iranti status [--scope user|system] [--json]', 'Show runtime roots, bindings, and known instances.'],
         ['iranti upgrade [--check] [--dry-run] [--yes] [--all] [--target auto|npm-global|npm-repo|python[,python]] [--json]', 'Check or run CLI/runtime/package upgrades.'],
         ['iranti uninstall [--dry-run] [--yes] [--all] [--keep-data] [--keep-project-bindings] [--scan-root <dir[,dir2]>] [--json]', 'Remove Iranti packages and, with --all, runtime data and project integrations.'],
         ['iranti handshake [--instance <name> | --project-env <file>] [--agent <id>] [--task <text>] [--recent <msg1||msg2>] [--recent-file <path>] [--json]', 'Manually inspect Attendant handshake output.'],
         ['iranti attend [message] [--instance <name> | --project-env <file>] [--agent <id>] [--context <text> | --context-file <path>] [--entity-hint <entity>] [--force] [--max-facts <n>] [--json]', 'Manually inspect turn-level memory injection decisions.'],
+        ['iranti handoff task/<task_id> [--instance <name> | --project-env <file>] [--agent <id>] --next-step <text> [--status <state>] [--owner <agent-id>] [--blockers <a||b>] [--artifacts <path1||path2>] [--project-entity <entity>] [--notes <text>] [--source <label>] [--confidence <n>] [--json]', 'Write a standardized shared-memory handoff for Claude/Codex collaboration.'],
         ['iranti chat [--agent <agent-id>] [--provider <provider>] [--model <model>]', 'Open the local interactive chat shell.'],
         ['iranti resolve [--dir <escalation-dir>]', 'Walk through pending escalation files.'],
     ]);
@@ -5021,6 +5748,10 @@ async function main() {
         subcommand: args.subcommand,
         cwd: process.cwd(),
     });
+    if (args.command === '--version' || args.command === 'version' || hasFlag(args, 'version')) {
+        console.log(getPackageVersion());
+        return;
+    }
     if (!args.command || args.command === 'help' || args.command === '--help') {
         printHelp();
         return;
@@ -5162,6 +5893,10 @@ async function main() {
         await attendCommand(args);
         return;
     }
+    if (args.command === 'handoff') {
+        await handoffCommand(args);
+        return;
+    }
     if (args.command === 'chat') {
         await chatCommand(args);
         return;