forkit-connect 0.1.5 → 0.1.6

package/dist/cli.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
 const node_readline_1 = require("node:readline");
 const promises_1 = require("node:readline/promises");
 const node_process_1 = require("node:process");
@@ -9,9 +13,15 @@ const daemon_1 = require("./v1/daemon");
 const service_1 = require("./v1/service");
 const discovery_1 = require("./v1/discovery");
 const heartbeat_1 = require("./v1/heartbeat");
+const runtime_activity_1 = require("./v1/runtime-activity");
+const runtime_editor_activity_1 = require("./v1/runtime-editor-activity");
+const runtime_observation_runner_1 = require("./v1/runtime-observation-runner");
+const runtime_context_1 = require("./v1/runtime-context");
 const update_1 = require("./v1/update");
+const repo_discovery_1 = require("./v1/repo-discovery");
 const api_1 = require("./v1/api");
 const credential_store_1 = require("./v1/credential-store");
+const runtime_registration_1 = require("./v1/runtime-registration");
 const DEFAULT_BASE_URL = process.env.FORKIT_API_URL ?? process.env.FORKIT_BASE_URL ?? 'https://www.forkit.dev';
 const TRAIN_EVENT_TYPES = [
     'training_started',
@@ -78,13 +88,14 @@ const PUBLIC_COMMANDS = [
     ['inbox', 'Review the Smart Registration Inbox'],
     ['sync', 'Flush queued drafts and lifecycle metadata'],
     ['workspace', 'List, select, or inspect optional governed workspace/project scope'],
-    ['runtime', 'Review local runtime discovery and runtime health'],
+    ['runtime', 'Register or review governed runtimes for the current repo/worktree'],
     ['register', 'Register ready local models into the current scope'],
     ['ignore', 'Ignore one detected local model'],
     ['doctor', 'Run local environment diagnostics'],
 ];
 const ADVANCED_COMMAND_GROUPS = [
     ['connect', 'Model connection, runtime review, and handoff utilities'],
+    ['runtime', 'Repo-scoped runtime observation and journaling utilities'],
     ['review', 'Summarize discovered but unconnected items'],
     ['doctor', 'Run local environment diagnostics'],
     ['workspaces', 'List accessible workspaces after sign-in'],
@@ -108,7 +119,7 @@ const ADVANCED_COMMAND_GROUPS = [
 function usage() {
     console.log('Usage: forkit-connect <init|login|logout|status|changes|start|stop|scan|inbox|sync|workspace|runtime|register|ignore|doctor> [options]');
     console.log('       forkit-connect workspace <list|select|create|status> [options]');
-    console.log('       forkit-connect runtime <review|status> [options]');
+    console.log('       forkit-connect runtime <register|review|status> [options]');
     console.log('Public commands:');
     for (const [command, description] of PUBLIC_COMMANDS) {
         console.log(`  ${command.padEnd(10)} ${description}`);
@@ -118,7 +129,15 @@ function usage() {
     console.log('  --project-name <text>   Project name used by workspace create/select');
     console.log('  --project-description <text> Optional project description used by workspace create/select');
     console.log('  --json                  Print machine-readable output when supported');
+    console.log('  --name <value>          Runtime or metric name depending on command');
     console.log('  --model <value>         Model name used by register');
+    console.log('  --entrypoint <path>     Relative project path used by runtime register');
+    console.log('  --source-url <url>      Source URL override used by runtime register');
+    console.log('  --subject-type <type>   Runtime subject type used by runtime register');
+    console.log('  --deployment-environment <value> Runtime environment used by runtime register');
+    console.log('  --show-key              Print the raw runtime API key when one is created');
+    console.log('  --no-api-key            Skip automatic runtime API key creation');
+    console.log('  --dry-run               Show the inferred runtime payload without creating it');
     console.log('  --all-ready             Register every ready local model in the current scope');
     console.log('  --ignore-model <name>   Ignore detected model by name with --ignore-digest');
     console.log('  --ignore-digest <sha>   Digest used with --ignore-model');
@@ -133,6 +152,8 @@ function advancedUsage() {
     console.log('Advanced commands:');
     console.log('  forkit-connect connect <modelNameOrDiscoveryHash>');
     console.log('  forkit-connect connect <start|init|status|inbox|services|permissions|handoff|evolution review|runtime review|runtime status>');
+    console.log('  forkit-connect runtime target <add|list|remove|status> [options]');
+    console.log('  forkit-connect runtime observe --gaid <gaid> [options]');
     console.log('  forkit-connect <review|workspaces|projects|bind|drafts|publish|bound|heartbeat|update-check|config|daemon|pulse|c2|train|agent|tray|notify> [options]');
     for (const [command, description] of ADVANCED_COMMAND_GROUPS) {
         console.log(`  ${command.padEnd(12)} ${description}`);
@@ -157,13 +178,15 @@ function advancedUsage() {
     console.log('  --heartbeat-gaid <gaid> Queue heartbeat runtime signal event for GAID');
     console.log('  --heartbeat-key <key>   API key used for heartbeat runtime signal event');
     console.log('                          Also used by: c2 set-key (stores key + backfills events)');
-    console.log('  --gaid <gaid>           Passport GAID used by c2 run-log emit');
-    console.log('  --api-key <key>         Runtime signal API key used by c2 run-log emit');
+    console.log('  --gaid <gaid>           Runtime or passport GAID used by runtime observe and c2 run-log emit');
+    console.log('  --api-key <key>         Runtime signal API key used by runtime observe and c2 run-log emit');
+    console.log('  --repo-root <path>      Repo root used by runtime target add (defaults to current repo/worktree)');
     console.log('  --provider <name>       Provider label used by c2 run-log emit');
     console.log('  --service-name <name>   Service/agent/workflow label used by c2 run-log emit');
     console.log('  --prompt-tokens <n>     Prompt tokens used by c2 run-log emit');
     console.log('  --completion-tokens <n> Completion tokens used by c2 run-log emit');
     console.log('  --client-name <name>    Optional repo/runtime client label used by c2 run-log emit');
+    console.log('  --command-label <name>  Operator label used by runtime observe and c2 run-log emit');
     console.log('  --actor-labels <csv>    Actor labels used by c2 run-log emit (for example: Codex,Claude)');
     console.log('  --task-labels <csv>     Task or chat labels used by c2 run-log emit');
     console.log('  --folder-labels <csv>   Relative folder labels used by c2 run-log emit');
@@ -172,6 +195,7 @@ function advancedUsage() {
     console.log('  --cpu-percent <n>       Scoped CPU percentage used by c2 run-log emit');
     console.log('  --memory-mb <n>         Scoped memory usage used by c2 run-log emit');
     console.log('  --vram-mb <n>           Device VRAM usage used by c2 run-log emit');
+    console.log('  --emit-ambient          Include ambient tool detections in runtime observe JSON output');
     console.log('  --draft-only            Allow draft creation even when governed publish capacity is full');
 }
 function showUsage() {
@@ -198,6 +222,15 @@ function getNumericArg(flag) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function getListArg(flag) {
+    const value = getArg(flag);
+    if (!value)
+        return [];
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
 function isHelpCommand(command) {
     return command === 'help' || command === '--help' || command === '-h' || command === '--advanced-help';
 }
@@ -345,6 +378,132 @@ function formatRemainingLimit(limit, used, singular, plural = `${singular}s`) {
 function isCapacityExhausted(limit, remaining) {
     return Number.isFinite(limit) && Number(remaining) <= 0;
 }
+function shouldCollectCodexThreads(input) {
+    const haystack = [
+        input.provider,
+        input.serviceName,
+        ...input.actorLabels,
+    ]
+        .join(' ')
+        .trim()
+        .toLowerCase();
+    return haystack.includes('codex');
+}
+function shouldCollectCopilotActivity(input) {
+    const haystack = [
+        input.provider,
+        input.serviceName,
+        ...input.actorLabels,
+    ]
+        .join(' ')
+        .trim()
+        .toLowerCase();
+    return haystack.includes('copilot');
+}
+function shouldCollectClaudeActivity(input) {
+    const haystack = [
+        input.provider,
+        input.serviceName,
+        ...input.actorLabels,
+    ]
+        .join(' ')
+        .trim()
+        .toLowerCase();
+    return haystack.includes('claude');
+}
+function buildCliRuntimeRunActivityEnvelope(input) {
+    const cwd = process.cwd();
+    const repo = (0, repo_discovery_1.detectRepository)(cwd);
+    const changedFiles = (0, repo_discovery_1.listRepositoryChangedFiles)(cwd);
+    const runtimeContext = repo.isGitRepo && repo.rootPath
+        ? ((0, runtime_context_1.readRuntimeContext)(repo.rootPath) ?? (0, runtime_context_1.buildRuntimeContextRecord)({
+            clientName: input.clientName || null,
+            defaultLabel: node_path_1.default.basename(repo.rootPath),
+        }))
+        : null;
+    const promptTokens = Number.isFinite(input.promptTokens) ? Math.max(0, Math.trunc(Number(input.promptTokens))) : 0;
+    const completionTokens = Number.isFinite(input.completionTokens) ? Math.max(0, Math.trunc(Number(input.completionTokens))) : 0;
+    const cachedPromptTokens = Number.isFinite(input.cachedPromptTokens) ? Math.max(0, Math.trunc(Number(input.cachedPromptTokens))) : undefined;
+    const reasoningTokens = Number.isFinite(input.reasoningTokens) ? Math.max(0, Math.trunc(Number(input.reasoningTokens))) : undefined;
+    const totalTokens = promptTokens + completionTokens;
+    const actorLabels = getListArg('--actor-labels');
+    const explicitTaskLabels = getListArg('--task-labels');
+    const explicitModelLabels = getListArg('--model-labels');
+    const codexAutoThreads = explicitTaskLabels.length === 0 && shouldCollectCodexThreads({
+        provider: input.provider,
+        serviceName: input.serviceName,
+        actorLabels,
+    })
+        ? (0, runtime_editor_activity_1.collectCodexEditorThreads)(repo)
+        : [];
+    const copilotAutoActivity = (explicitTaskLabels.length === 0 || explicitModelLabels.length === 0) && shouldCollectCopilotActivity({
+        provider: input.provider,
+        serviceName: input.serviceName,
+        actorLabels,
+    })
+        ? (0, runtime_editor_activity_1.collectCopilotEditorActivity)(repo)
+        : { threads: [], modelLabels: [] };
+    const claudeAutoActivity = (explicitTaskLabels.length === 0 || explicitModelLabels.length === 0) && shouldCollectClaudeActivity({
+        provider: input.provider,
+        serviceName: input.serviceName,
+        actorLabels,
+    })
+        ? (0, runtime_editor_activity_1.collectClaudeProjectActivity)(repo)
+        : { threads: [], modelLabels: [] };
+    const autoThreads = [
+        ...codexAutoThreads,
+        ...(explicitTaskLabels.length === 0 ? copilotAutoActivity.threads : []),
+        ...(explicitTaskLabels.length === 0 ? claudeAutoActivity.threads : []),
+    ];
+    const taskLabels = explicitTaskLabels.length > 0 ? explicitTaskLabels : autoThreads.map((thread) => thread.threadLabel);
+    const modelLabels = explicitModelLabels.length > 0
+        ? explicitModelLabels
+        : [...copilotAutoActivity.modelLabels, ...claudeAutoActivity.modelLabels];
+    const clientName = input.clientName || runtimeContext?.clientName || null;
+    return (0, runtime_activity_1.buildRuntimeActivityMetadata)({
+        cwd,
+        repo,
+        changedFiles,
+        provider: input.provider,
+        model: input.model,
+        serviceName: input.serviceName,
+        serviceKind: input.serviceKind ?? null,
+        commandLabel: input.commandLabel ?? null,
+        status: input.status ?? null,
+        startedAt: input.startedAt || new Date().toISOString(),
+        endedAt: input.endedAt || null,
+        summary: input.summary ?? null,
+        clientName,
+        stableSubjectId: runtimeContext?.subjectId,
+        stableWorktreeId: runtimeContext?.worktreeId,
+        actorLabels,
+        taskLabels,
+        activityThreads: autoThreads.map((thread) => ({
+            title: thread.threadLabel,
+            taskId: thread.threadId ?? null,
+            openedAt: thread.createdAt ?? null,
+            lastActiveAt: thread.lastActiveAt ?? null,
+            provider: thread.provider,
+            actorLabel: thread.actorLabel,
+            workspaceHost: thread.workspaceHost,
+            folderScope: thread.folderScope ?? null,
+        })),
+        folderLabels: getListArg('--folder-labels'),
+        fileLabels: getListArg('--file-labels'),
+        modelLabels,
+        promptTokens,
+        completionTokens,
+        cachedPromptTokens,
+        reasoningTokens,
+        totalTokens,
+        latencyMs: input.latencyMs,
+        resources: {
+            cpuPercent: getNumericArg('--cpu-percent'),
+            memoryMb: getNumericArg('--memory-mb'),
+            vramMb: getNumericArg('--vram-mb'),
+        },
+    });
+}
 function formatWorkspaceAccessLine(workspace) {
     const workspaceId = String(workspace.id || workspace.gaid || workspace.passportGaid || 'unknown');
     return `- ${summarizeWorkspaceLabel(workspace)} | id=${workspaceId}`;
@@ -481,6 +640,72 @@ function readPassportList(body) {
     }
     return passports.filter((item) => !!item && typeof item === 'object' && !Array.isArray(item));
 }
+function isRuntimeListResponse(body) {
+    return Boolean(body) && typeof body === 'object' && !Array.isArray(body);
+}
+function isRuntimeCreateResponse(body) {
+    return Boolean(body) && typeof body === 'object' && !Array.isArray(body);
+}
+function isApiKeyCreateResponse(body) {
+    return Boolean(body) && typeof body === 'object' && !Array.isArray(body);
+}
+function readRuntimeList(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        return [];
+    }
+    const runtimes = body.runtimes;
+    if (!Array.isArray(runtimes)) {
+        return [];
+    }
+    return runtimes.filter((item) => !!item && typeof item === 'object' && !Array.isArray(item));
+}
+function readRuntimeIdentityMetadata(runtime) {
+    const metadata = runtime.metadata;
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+        return null;
+    }
+    const runtimeIdentity = metadata.runtimeIdentity;
+    return runtimeIdentity && typeof runtimeIdentity === 'object' && !Array.isArray(runtimeIdentity)
+        ? runtimeIdentity
+        : null;
+}
+function findExistingRuntimeForIdentity(runtimes, input) {
+    const targetWorkspaceId = input.workspaceId.trim();
+    const targetProjectId = input.projectId.trim();
+    for (const runtime of runtimes) {
+        const runtimeWorkspaceId = String(runtime.workspaceId || runtime.workspace_id || '').trim();
+        const runtimeProjectId = String(runtime.projectId || runtime.project_id || '').trim();
+        if (runtimeWorkspaceId !== targetWorkspaceId || runtimeProjectId !== targetProjectId) {
+            continue;
+        }
+        const runtimeIdentity = readRuntimeIdentityMetadata(runtime);
+        if (!runtimeIdentity) {
+            continue;
+        }
+        const repoRootFingerprint = String(runtimeIdentity.repoRootFingerprint || '').trim();
+        const worktreeId = String(runtimeIdentity.worktreeId || '').trim();
+        const entrypoint = String(runtimeIdentity.entrypointRelativePath || '.').trim() || '.';
+        if (repoRootFingerprint === input.repoRootFingerprint
+            && worktreeId === input.worktreeId
+            && entrypoint === input.entrypointRelativePath) {
+            return runtime;
+        }
+    }
+    return null;
+}
+function formatRuntimeToolingHintList(value) {
+    if (!Array.isArray(value))
+        return 'No tooling hints recorded';
+    const labels = value
+        .map((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return null;
+        const label = String(entry.label || entry.key || '').trim();
+        return label || null;
+    })
+        .filter((entry) => Boolean(entry));
+    return labels.length ? labels.join(', ') : 'No tooling hints recorded';
+}
 function formatPassportLine(passport) {
     const gaid = String(passport.gaid || passport.id || 'unknown');
     const name = String(passport.name || 'Unnamed passport');
@@ -1156,6 +1381,25 @@ function printRuntimeStatus(status) {
         console.log(`- latest event=${status.latest_runtime_lifecycle_event}`);
     }
 }
+function printRuntimeTargetList(service, options) {
+    const targets = service.listRuntimeObserverTargets();
+    const daemon = (0, daemon_1.getDaemonHealth)(service);
+    if (options?.json) {
+        printJson({
+            daemon,
+            totalTargets: targets.length,
+            targets: targets.map((target) => ({
+                ...target,
+                runtimeSignalKeyConfigured: service.hasRuntimeSignalKey(target.runtime_gaid),
+            })),
+        });
+        return;
+    }
+    console.log(`[forkit-connect] Runtime targets=${targets.length} | daemon=${daemon.running ? `running:${daemon.pid}` : 'stopped'}`);
+    for (const target of targets) {
+        console.log(`- gaid=${shortId(target.runtime_gaid)} | repo=${target.repo_root} | client=${target.client_name || 'n/a'} | key=${service.hasRuntimeSignalKey(target.runtime_gaid) ? 'ready' : 'missing'} | last_emit=${target.last_emitted_at || 'never'}${target.last_error ? ` | error=${target.last_error}` : ''}`);
+    }
+}
 function formatSmartInboxActionValue(action, itemType, connectableModelName) {
     switch (action) {
         case 'connect_existing_passport':
@@ -3172,6 +3416,221 @@ async function run() {
         cachedCliAccountLimitsAt = now;
         return resolved;
     };
+    const runRuntimeRegister = async () => {
+        const storedSessionRef = String(service.readSessionRef() || '').trim();
+        if (!storedSessionRef) {
+            console.error('Not authenticated. Run forkit-connect login first.');
+            process.exitCode = 2;
+            return;
+        }
+        const sessionState = await checkBackendSessionState(service);
+        if (sessionState === 'expired') {
+            console.error('Session expired. Run forkit-connect login again.');
+            process.exitCode = 2;
+            return;
+        }
+        if (sessionState === 'missing') {
+            console.error('Not authenticated. Run forkit-connect login first.');
+            process.exitCode = 2;
+            return;
+        }
+        if (sessionState === 'unavailable') {
+            console.error('Forkit.dev is unavailable right now. Try again when the backend is reachable.');
+            process.exitCode = 2;
+            return;
+        }
+        const state = service.getStateStore().readState();
+        const boundWorkspaceId = String(workspaceId || state.workspace_binding.workspaceId || '').trim();
+        const boundProjectId = String(projectId || state.project_binding.projectId || '').trim();
+        if (!boundWorkspaceId || !boundProjectId) {
+            console.error('Runtime registration needs a governed workspace and project. Run forkit-connect workspace select first or pass --workspace and --project.');
+            process.exitCode = 2;
+            return;
+        }
+        let runtimeDraft;
+        try {
+            runtimeDraft = (0, runtime_registration_1.inspectRuntimeProject)({
+                cwd: process.cwd(),
+                name: getArg('--name'),
+                description: descriptionArg,
+                sourceUrl: getArg('--source-url'),
+                entrypointRelativePath: getArg('--entrypoint'),
+                subjectType: (getArg('--subject-type') || null),
+                deploymentEnvironment: getArg('--deployment-environment'),
+                connectRuntimeId: state.runtime_identity.runtimeId,
+            });
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : 'Runtime inspection failed.');
+            process.exitCode = 2;
+            return;
+        }
+        const resultPayload = {
+            name: runtimeDraft.name,
+            description: runtimeDraft.description,
+            sourceUrl: runtimeDraft.sourceUrl,
+            workspaceId: boundWorkspaceId,
+            projectId: boundProjectId,
+            metadata: runtimeDraft.metadata,
+            runtimeIdentity: runtimeDraft.runtimeIdentity,
+        };
+        if (hasFlag('--dry-run')) {
+            printJson({
+                ok: true,
+                action: 'dry_run',
+                payload: resultPayload,
+                inferred_project: {
+                    repo_root: runtimeDraft.snapshot.repoRootName,
+                    branch: runtimeDraft.snapshot.branch,
+                    commit: runtimeDraft.snapshot.commit,
+                    dirty: runtimeDraft.snapshot.dirty,
+                    entrypoint: runtimeDraft.snapshot.relativeEntrypoint,
+                    tooling: runtimeDraft.snapshot.detectedTooling,
+                },
+            });
+            return;
+        }
+        const api = buildWorkspaceApi();
+        const runtimeListResult = await api.getRuntimesMine(100);
+        if (!runtimeListResult.ok || !isRuntimeListResponse(runtimeListResult.body)) {
+            console.error(`[forkit-connect] Runtime lookup failed (${runtimeListResult.status}).`);
+            if (runtimeListResult.body) {
+                console.error(typeof runtimeListResult.body === 'string' ? runtimeListResult.body : JSON.stringify(runtimeListResult.body));
+            }
+            process.exitCode = 2;
+            return;
+        }
+        const runtimes = readRuntimeList(runtimeListResult.body);
+        const existingRuntime = findExistingRuntimeForIdentity(runtimes, {
+            workspaceId: boundWorkspaceId,
+            projectId: boundProjectId,
+            repoRootFingerprint: runtimeDraft.runtimeIdentity.repoRootFingerprint,
+            worktreeId: runtimeDraft.runtimeIdentity.worktreeId,
+            entrypointRelativePath: runtimeDraft.runtimeIdentity.entrypointRelativePath,
+        });
+        let action = existingRuntime ? 'existing' : 'created';
+        let runtimeRecord = existingRuntime;
+        if (!runtimeRecord) {
+            const createResult = await api.createRuntime(resultPayload);
+            if (!createResult.ok || !isRuntimeCreateResponse(createResult.body) || !createResult.body.runtime) {
+                const errorBody = createResult.body && typeof createResult.body === 'object'
+                    ? createResult.body
+                    : null;
+                const message = typeof errorBody?.error === 'string'
+                    ? errorBody.error
+                    : `[forkit-connect] Runtime registration failed (${createResult.status}).`;
+                console.error(message);
+                if (createResult.body) {
+                    console.error(typeof createResult.body === 'string' ? createResult.body : JSON.stringify(createResult.body));
+                }
+                process.exitCode = 2;
+                return;
+            }
+            runtimeRecord = createResult.body.runtime;
+        }
+        const runtimeGaid = String(runtimeRecord?.gaid || '').trim();
+        if (!runtimeGaid) {
+            console.error('Runtime registration returned no GAID.');
+            process.exitCode = 2;
+            return;
+        }
+        const shouldCreateApiKey = !hasFlag('--no-api-key') && !service.hasStoredRuntimeSignalKey(runtimeGaid);
+        let apiKeyStored = false;
+        let apiKeyCreated = false;
+        let keyId = null;
+        let rawKeyToDisplay = null;
+        let keyStorageWarning = null;
+        if (shouldCreateApiKey) {
+            const apiKeyResult = await api.createRuntimeApiKey(runtimeGaid, 'Forkit Connect runtime');
+            if (!apiKeyResult.ok || !isApiKeyCreateResponse(apiKeyResult.body) || !apiKeyResult.body.rawKey) {
+                keyStorageWarning = `Runtime created, but runtime key provisioning failed (${apiKeyResult.status}).`;
+                if (apiKeyResult.body) {
+                    const detail = typeof apiKeyResult.body === 'string' ? apiKeyResult.body : JSON.stringify(apiKeyResult.body);
+                    keyStorageWarning = `${keyStorageWarning} ${detail}`;
+                }
+            }
+            else {
+                apiKeyCreated = true;
+                keyId = String(apiKeyResult.body.keyId || '').trim() || null;
+                const rawKey = String(apiKeyResult.body.rawKey || '').trim();
+                try {
+                    const configured = service.configureRuntimeSignalKey({
+                        gaid: runtimeGaid,
+                        apiKey: rawKey,
+                    });
+                    apiKeyStored = configured.stored;
+                    if (hasFlag('--show-key')) {
+                        rawKeyToDisplay = rawKey;
+                    }
+                }
+                catch (error) {
+                    if (error instanceof credential_store_1.ConnectCredentialStoreError) {
+                        keyStorageWarning = error.message;
+                        rawKeyToDisplay = rawKey;
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+        }
+        else if (!hasFlag('--no-api-key')) {
+            apiKeyStored = true;
+        }
+        if (hasFlag('--json')) {
+            printJson({
+                ok: true,
+                action,
+                runtime: runtimeRecord,
+                logging_ready: hasFlag('--no-api-key') ? false : apiKeyStored,
+                api_key: {
+                    created: apiKeyCreated,
+                    stored: apiKeyStored,
+                    keyId,
+                    ...(rawKeyToDisplay ? { rawKey: rawKeyToDisplay } : {}),
+                    warning: keyStorageWarning,
+                },
+                inferred_project: {
+                    repo_root: runtimeDraft.snapshot.repoRootName,
+                    branch: runtimeDraft.snapshot.branch,
+                    commit: runtimeDraft.snapshot.commit,
+                    dirty: runtimeDraft.snapshot.dirty,
+                    entrypoint: runtimeDraft.snapshot.relativeEntrypoint,
+                    tooling: runtimeDraft.snapshot.detectedTooling,
+                },
+            });
+            return;
+        }
+        console.log(action === 'created' ? 'Runtime registered.' : 'Runtime already exists. Reusing governed runtime.');
+        console.log(`Runtime: ${runtimeDraft.name}`);
+        console.log(`GAID: ${runtimeGaid}`);
+        console.log(`Scope: workspace=${boundWorkspaceId} | project=${boundProjectId}`);
+        console.log(`Project: ${runtimeDraft.snapshot.repoRootName} | branch=${runtimeDraft.snapshot.branch || 'detached'} | commit=${String(runtimeDraft.snapshot.commit || 'unknown').slice(0, 12)} | dirty=${String(runtimeDraft.snapshot.dirty)}`);
+        console.log(`Entrypoint: ${runtimeDraft.snapshot.relativeEntrypoint}`);
+        console.log(`Tooling: ${formatRuntimeToolingHintList(runtimeDraft.snapshot.detectedTooling)}`);
+        if (runtimeDraft.sourceUrl) {
+            console.log(`Source URL: ${runtimeDraft.sourceUrl}`);
+        }
+        if (hasFlag('--no-api-key')) {
+            console.log('Runtime key: skipped by request (--no-api-key).');
+            return;
+        }
+        if (apiKeyStored) {
+            console.log(apiKeyCreated
+                ? `Runtime key stored securely${keyId ? ` (keyId=${keyId})` : ''}.`
+                : 'Runtime key already stored locally for this runtime.');
+        }
+        if (keyStorageWarning) {
+            console.log(`Runtime key warning: ${keyStorageWarning}`);
+        }
+        if (rawKeyToDisplay) {
+            console.log('Runtime API key (shown once):');
+            console.log(rawKeyToDisplay);
+        }
+        if (!apiKeyStored && !rawKeyToDisplay) {
+            console.log('Runtime logging is not ready yet. Create or attach a runtime key from Forkit.dev.');
+        }
+    };
     const createProjectInWorkspace = async (api, selectedWorkspaceId, options) => {
         let nextProjectName = projectNameArg;
         let nextProjectDescription = projectDescriptionArg;
@@ -3616,30 +4075,6 @@ async function run() {
         await runPublicSync();
         return;
     }
-    if (command === 'runtime') {
-        const subcommand = args[1] || 'review';
-        if (subcommand === 'review') {
-            const summary = service.getRuntimePassportReview();
-            if (hasFlag('--json')) {
-                printJson(summary);
-                return;
-            }
-            printRuntimeReview(summary);
-            return;
-        }
-        if (subcommand === 'status') {
-            const status = service.getRuntimePassportStatus();
-            if (hasFlag('--json')) {
-                printJson(status);
-                return;
-            }
-            printRuntimeStatus(status);
-            return;
-        }
-        console.error('Usage: forkit-connect runtime <review|status>');
-        process.exitCode = 2;
-        return;
-    }
     if (command === 'workspace') {
         const subcommand = args[1] || 'status';
         try {
@@ -3693,6 +4128,269 @@ async function run() {
         process.exitCode = 2;
         return;
     }
+    if (command === 'runtime') {
+        const subcommand = args[1];
+        const nestedCommand = args[2];
+        if (isHelpCommand(subcommand) || (subcommand === 'register' && isHelpCommand(nestedCommand))) {
+            showUsage();
+            return;
+        }
+        if ((subcommand === 'target' || subcommand === 'observe') && isHelpCommand(nestedCommand)) {
+            advancedUsage();
+            return;
+        }
+        if (subcommand === 'review') {
+            const summary = service.getRuntimePassportReview();
+            if (hasFlag('--json')) {
+                printJson(summary);
+                return;
+            }
+            printRuntimeReview(summary);
+            return;
+        }
+        if (subcommand === 'status') {
+            const status = service.getRuntimePassportStatus();
+            if (hasFlag('--json')) {
+                printJson(status);
+                return;
+            }
+            printRuntimeStatus(status);
+            return;
+        }
+        if (subcommand === 'register' || !subcommand) {
+            await runRuntimeRegister();
+            return;
+        }
+        if (subcommand === 'target') {
+            const action = args[2];
+            if (action === 'list' || action === 'status') {
+                printRuntimeTargetList(service, { json: hasFlag('--json') });
+                return;
+            }
+            if (action === 'remove') {
+                const gaid = getArg('--gaid') ?? getArg('--heartbeat-gaid');
+                if (!gaid) {
+                    console.error('[forkit-connect] runtime target remove requires --gaid.');
+                    process.exitCode = 1;
+                    return;
+                }
+                const removed = service.removeRuntimeObserverTarget(gaid);
+                if (!removed) {
+                    console.error('[forkit-connect] Runtime target not found for that GAID.');
+                    process.exitCode = 2;
+                    return;
+                }
+                if (hasFlag('--json')) {
+                    printJson({ removed: true, gaid });
+                    return;
+                }
+                console.log(`Removed runtime target ${gaid}.`);
+                return;
+            }
+            if (action === 'add') {
+                const gaid = getArg('--gaid') ?? getArg('--heartbeat-gaid');
+                if (!gaid) {
+                    console.error('[forkit-connect] runtime target add requires --gaid.');
+                    process.exitCode = 1;
+                    return;
+                }
+                const repoRootArg = getArg('--repo-root');
+                const cwd = repoRootArg ? node_path_1.default.resolve(repoRootArg) : process.cwd();
+                const repo = (0, repo_discovery_1.detectRepository)(cwd);
+                const rootPath = repo.rootPath || repo.cwd;
+                const existingTarget = service.listRuntimeObserverTargets().find((item) => item.runtime_gaid === gaid) ?? null;
+                const runtimeContext = repo.isGitRepo && repo.rootPath
+                    ? ((0, runtime_context_1.readRuntimeContext)(repo.rootPath) ?? (0, runtime_context_1.buildRuntimeContextRecord)({
+                        existing: existingTarget
+                            ? {
+                                schemaVersion: 'forkit.runtime-context.v1',
+                                ...(existingTarget.client_name ? { clientName: existingTarget.client_name } : {}),
+                                ...(existingTarget.subject_id ? { subjectId: existingTarget.subject_id } : {}),
+                                ...(existingTarget.worktree_id ? { worktreeId: existingTarget.worktree_id } : {}),
+                            }
+                            : null,
+                        clientName: getArg('--client-name') || existingTarget?.client_name || null,
+                        defaultLabel: node_path_1.default.basename(repo.rootPath),
+                    }))
+                    : null;
+                const apiKey = getArg('--api-key') ?? getArg('--heartbeat-key') ?? process.env.FORKIT_RUNTIME_SIGNAL_API_KEY ?? null;
+                if (apiKey) {
+                    service.configureRuntimeSignalKey({ gaid, apiKey });
+                }
+                const target = service.registerRuntimeObserverTarget({
+                    gaid,
+                    repoRoot: rootPath,
+                    clientName: getArg('--client-name') || runtimeContext?.clientName || existingTarget?.client_name || node_path_1.default.basename(rootPath),
+                    subjectId: runtimeContext?.subjectId ?? existingTarget?.subject_id ?? null,
+                    worktreeId: runtimeContext?.worktreeId ?? existingTarget?.worktree_id ?? null,
+                });
+                let autoProvisioned = false;
+                if (!service.hasRuntimeSignalKey(gaid)) {
+                    try {
+                        const provisioning = await service.autoProvisionRuntimeSignalKeys({ suppressErrors: true });
+                        autoProvisioned = provisioning.provisioned.includes(gaid);
+                    }
+                    catch {
+                        autoProvisioned = false;
+                    }
+                }
+                const daemon = (0, daemon_1.getDaemonHealth)(service);
+                const runtimeSignalKeyConfigured = service.hasRuntimeSignalKey(gaid);
+                if (hasFlag('--json')) {
+                    printJson({
+                        stored: true,
+                        daemon,
+                        target,
+                        runtimeSignalKeyConfigured,
+                        autoProvisioned,
+                    });
+                    return;
+                }
+                console.log(`Stored runtime target ${gaid}.`);
+                console.log(`Repo root: ${target.repo_root}`);
+                console.log(`Client: ${target.client_name || 'n/a'}`);
+                console.log(`Runtime key: ${runtimeSignalKeyConfigured ? (autoProvisioned ? 'ready (auto-provisioned)' : 'ready') : 'missing'}`);
+                console.log(`Daemon: ${daemon.running ? `running (${daemon.pid})` : 'stopped'}`);
+                if (!daemon.running) {
+                    console.log('Next: run `forkit-connect start` to keep this runtime connected in the background.');
+                }
+                return;
+            }
+            console.error('Usage: forkit-connect runtime target <add|list|remove|status> [options]');
+            process.exitCode = 2;
+            return;
+        }
+        if (subcommand === 'observe') {
+            const gaid = getArg('--gaid') ?? getArg('--heartbeat-gaid');
+            if (!gaid) {
+                console.error('[forkit-connect] runtime observe requires --gaid.');
+                console.error('[forkit-connect] Use the governed runtime GAID from Forkit.dev.');
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const cwd = process.cwd();
+                const repo = (0, repo_discovery_1.detectRepository)(cwd);
+                const apiKey = getArg('--api-key') ?? getArg('--heartbeat-key') ?? process.env.FORKIT_RUNTIME_SIGNAL_API_KEY ?? null;
+                if (apiKey) {
+                    service.configureRuntimeSignalKey({ gaid, apiKey });
+                }
+                const existingTarget = service.listRuntimeObserverTargets().find((item) => item.runtime_gaid === gaid) ?? null;
+                const runtimeContext = repo.isGitRepo && repo.rootPath
+                    ? ((0, runtime_context_1.readRuntimeContext)(repo.rootPath) ?? (0, runtime_context_1.buildRuntimeContextRecord)({
+                        existing: existingTarget
+                            ? {
+                                schemaVersion: 'forkit.runtime-context.v1',
+                                ...(existingTarget.client_name ? { clientName: existingTarget.client_name } : {}),
+                                ...(existingTarget.subject_id ? { subjectId: existingTarget.subject_id } : {}),
+                                ...(existingTarget.worktree_id ? { worktreeId: existingTarget.worktree_id } : {}),
+                            }
+                            : null,
+                        clientName: getArg('--client-name') || existingTarget?.client_name || null,
+                        defaultLabel: node_path_1.default.basename(repo.rootPath),
+                    }))
+                    : null;
+                const target = service.registerRuntimeObserverTarget({
+                    gaid,
+                    repoRoot: repo.rootPath || repo.cwd,
+                    clientName: getArg('--client-name') || runtimeContext?.clientName || existingTarget?.client_name || null,
+                    subjectId: runtimeContext?.subjectId ?? existingTarget?.subject_id ?? null,
+                    worktreeId: runtimeContext?.worktreeId ?? existingTarget?.worktree_id ?? null,
+                });
+                const collection = await (0, runtime_observation_runner_1.collectRuntimeObservation)({
+                    gaid,
+                    cwd,
+                    clientName: target.client_name,
+                    commandLabel: getArg('--command-label') ?? 'runtime-observer',
+                    target,
+                });
+                if (!collection.accepted) {
+                    service.updateRuntimeObserverTargetResult({
+                        gaid,
+                        observedAt: collection.observedAt,
+                        summary: null,
+                        error: collection.reason,
+                    });
+                    if (hasFlag('--json')) {
+                        printJson({
+                            accepted: false,
+                            reason: collection.reason,
+                            runtime: { gaid },
+                            observations: hasFlag('--emit-ambient') ? [...collection.scopedObservations, ...collection.ambientObservations] : [],
+                            ambient_observations: collection.ambientObservations,
+                        });
+                        return;
+                    }
+                    console.log('No repo-scoped active tooling was observed for this runtime.');
+                    if (collection.ambientObservations.length > 0) {
+                        console.log(`Ambient tooling seen but not attributed: ${collection.ambientObservations.map((item) => item.label).join(', ')}`);
+                    }
+                    return;
+                }
+                const result = await (0, runtime_observation_runner_1.emitCollectedRuntimeObservation)(service, collection, { apiKey });
+                if (!result.ok) {
+                    const bodyRecord = result.body && typeof result.body === 'object' && !Array.isArray(result.body)
+                        ? result.body
+                        : null;
+                    service.updateRuntimeObserverTargetResult({
+                        gaid,
+                        observedAt: collection.observedAt,
+                        fingerprint: collection.fingerprint,
+                        summary: collection.summary,
+                        error: typeof result.body === 'string'
+                            ? result.body
+                            : bodyRecord && typeof bodyRecord.error === 'string'
+                                ? bodyRecord.error
+                                : `runtime_observer_emit_failed_${result.status || 'local'}`,
+                    });
+                    console.error(`[forkit-connect] Runtime observe failed (${result.status || 'local'}).`);
+                    if (result.body) {
+                        console.error(typeof result.body === 'string' ? result.body : JSON.stringify(result.body));
+                    }
+                    process.exitCode = 2;
+                    return;
+                }
+                service.updateRuntimeObserverTargetResult({
+                    gaid,
+                    observedAt: collection.observedAt,
+                    emittedAt: collection.observedAt,
+                    fingerprint: collection.fingerprint,
+                    summary: collection.summary,
+                    error: null,
+                });
+                if (hasFlag('--json')) {
+                    printJson({
+                        accepted: true,
+                        runtime: {
+                            gaid,
+                            rootPath: collection.repoRoot,
+                            relativePath: collection.relativePath,
+                        },
+                        observations: collection.scopedObservations,
+                        ambient_observations: hasFlag('--emit-ambient') ? collection.ambientObservations : [],
+                        response: result.body,
+                    });
+                    return;
+                }
+                console.log('Runtime observation recorded.');
+                console.log(`Runtime GAID: ${gaid}`);
+                console.log(`Repo root: ${collection.repoRoot}`);
+                console.log(`Scoped tooling: ${collection.scopedObservations.map((item) => `${item.label}${item.details && typeof item.details.primaryRole === 'string' ? `/${item.details.primaryRole}` : ''} (${item.activeProcessCount}${item.helperProcessCount > 0 ? `+${item.helperProcessCount} helper` : ''})`).join(', ')}`);
+                if (collection.ambientObservations.length > 0) {
+                    console.log(`Ambient tooling ignored: ${collection.ambientObservations.map((item) => item.label).join(', ')}`);
+                }
+                return;
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : 'runtime_observe_failed');
+                process.exitCode = 2;
+                return;
+            }
+        }
+        console.error('Usage: forkit-connect runtime <register|target|observe> [options]');
+        process.exitCode = 2;
+        return;
+    }
     if (command === 'ignore') {
         runPublicIgnore();
         return;
@@ -3890,6 +4588,32 @@ async function run() {
                 process.exitCode = 1;
                 return;
             }
+            const status = getArg('--status') ?? 'completed';
+            const startedAt = getArg('--started-at');
+            const endedAt = getArg('--ended-at');
+            const promptTokens = getNumericArg('--prompt-tokens');
+            const completionTokens = getNumericArg('--completion-tokens');
+            const cachedPromptTokens = getNumericArg('--cached-prompt-tokens');
+            const reasoningTokens = getNumericArg('--reasoning-tokens');
+            const latencyMs = getNumericArg('--latency-ms');
+            const summary = getArg('--summary');
+            const activityEnvelope = buildCliRuntimeRunActivityEnvelope({
+                provider,
+                model: runModel,
+                serviceName,
+                serviceKind: getArg('--service-kind') ?? 'custom',
+                commandLabel: getArg('--command-label'),
+                status,
+                startedAt,
+                endedAt,
+                summary,
+                clientName: getArg('--client-name'),
+                promptTokens,
+                completionTokens,
+                cachedPromptTokens,
+                reasoningTokens,
+                latencyMs,
+            });
             const result = await service.emitRuntimeRunLog({
                 gaid,
                 apiKey,
@@ -3899,17 +4623,19 @@ async function run() {
                 serviceKind: getArg('--service-kind') ?? 'custom',
                 runId: getArg('--run-id'),
                 externalRunId: getArg('--external-run-id'),
-                status: getArg('--status') ?? 'completed',
-                startedAt: getArg('--started-at'),
-                endedAt: getArg('--ended-at'),
-                promptTokens: getNumericArg('--prompt-tokens'),
-                completionTokens: getNumericArg('--completion-tokens'),
-                cachedPromptTokens: getNumericArg('--cached-prompt-tokens'),
-                reasoningTokens: getNumericArg('--reasoning-tokens'),
-                latencyMs: getNumericArg('--latency-ms'),
+                status,
+                startedAt,
+                endedAt,
+                promptTokens,
+                completionTokens,
+                cachedPromptTokens,
+                reasoningTokens,
+                latencyMs,
                 estimatedCostCents: getNumericArg('--estimated-cost-cents'),
                 currency: getArg('--currency') ?? 'USD',
-                summary: getArg('--summary'),
+                summary: activityEnvelope.summary ?? summary,
+                metadata: activityEnvelope.metadata,
+                steps: activityEnvelope.steps,
             });
             if (!result.ok) {
                 console.error(`[forkit-connect] Runtime run log emit failed (${result.status || 'local'}).`);