nexarch 0.11.4 → 0.12.1

package/dist/commands/check-in.js

@@ -2,8 +2,10 @@ import process from "process";
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { saveCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
+import { inferAccessibleApplicationRefs } from "../lib/application-context.js";
 function parseFlag(args, flag) {
     return args.includes(flag);
 }
@@ -35,6 +37,7 @@ function loadIdentity() {
 export async function checkIn(args) {
     const asJson = parseFlag(args, "--json");
     const agentKeyArg = parseOptionValue(args, "--agent-ref") ?? parseOptionValue(args, "--agent-key");
+    const applicationRefArg = parseOptionValue(args, "--application-ref");
     const creds = requireCredentials();
     const identity = loadIdentity();
     const agentKey = agentKeyArg ?? identity.agentKey;
@@ -47,19 +50,44 @@ export async function checkIn(args) {
         }
         return;
     }
+    const applicationContext = await inferAccessibleApplicationRefs({
+        companyId: creds.companyId,
+        explicitApplicationRefs: applicationRefArg ? [applicationRefArg] : undefined,
+    });
     const raw = await callMcpTool("nexarch_check_in", {
         agentRef: agentKey,
         agentKey,
+        applicationContext: applicationContext.accessibleApplicationRefs.length > 0
+            ? { accessibleApplicationRefs: applicationContext.accessibleApplicationRefs }
+            : undefined,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });
     const result = parseToolText(raw);
     const draftApplications = result.draftApplications ?? [];
     const proposedApplications = result.proposedApplications ?? [];
+    if (result.leaseToken && result.leaseIssuedAt && result.leaseExpiresAt) {
+        saveCheckInLease({
+            leaseToken: result.leaseToken,
+            leaseIssuedAt: result.leaseIssuedAt,
+            leaseExpiresAt: result.leaseExpiresAt,
+            policyBundleHash: result.policyBundleHash ?? null,
+            companyId: creds.companyId,
+            agentRef: agentKey,
+        });
+    }
     if (asJson) {
         process.stdout.write(JSON.stringify(result) + "\n");
         return;
     }
     const commands = result.commands ?? [];
+    if (result.leaseExpiresAt) {
+        console.log(`Check-in lease active until ${new Date(result.leaseExpiresAt).toLocaleString()}.`);
+    }
+    console.log(`Application context: ${applicationContext.detail}`);
+    for (const warning of result.warnings ?? []) {
+        if (warning.message)
+            console.log(`Warning: ${warning.message}`);
+    }
     if (commands.length === 0 && draftApplications.length === 0 && proposedApplications.length === 0) {
         console.log("No pending application-target commands found.");
         console.log("No draft or proposed applications need attention.");
@@ -73,7 +101,7 @@ export async function checkIn(args) {
         }
         for (const cmd of commands) {
             const claimable = cmd.claimable ? "yes" : "no";
-            const reason = cmd.claimReason ?? (cmd.claimable ? "application_access_confirmed" : "application_not_found_for_company");
+            const reason = cmd.claimReason ?? (cmd.claimable ? "application_access_confirmed" : "application_context_required_for_claim");
             console.log(`\n- ID         : ${cmd.id}`);
             console.log(`  Type       : ${cmd.command_type}`);
             console.log(`  Target     : ${cmd.target_entity_key ?? "(none)"}`);
@@ -83,12 +111,14 @@ export async function checkIn(args) {
                 console.log(`  Type ver   : ${cmd.command_type_version}`);
             if (cmd.resolved_runtime_handler)
                 console.log(`  Runtime    : ${cmd.resolved_runtime_handler}`);
-            if (cmd.claimable) {
-                console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"`);
-            }
+            if (cmd.claimGuidance)
+                console.log(`  Guidance   : ${cmd.claimGuidance}`);
+            console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"${cmd.target_entity_key ? ` --application-ref "${cmd.target_entity_key}"` : ""}`);
         }
         console.log("\nTo validate an application target is accessible in Nexarch before claiming:");
         console.log("  npx nexarch policy-controls --entity <application:key> --json");
+        console.log("If no application context was inferred, re-run with:");
+        console.log("  npx nexarch check-in --application-ref <application:key>");
     }
     else {
         console.log("No pending application-target commands found.");
@@ -124,8 +154,12 @@ export async function checkIn(args) {
                 console.log(`  Desc    : ${app.description}`);
             if (app.recommendationBasis)
                 console.log(`  Basis   : ${app.recommendationBasis}`);
+            if (app.recommendationStatus)
+                console.log(`  Status  : ${app.recommendationStatus}`);
             if (typeof app.recommendedTechnologyCount === "number")
                 console.log(`  Tech    : ${app.recommendedTechnologyCount} recommended`);
+            if (typeof app.capabilityGapCount === "number")
+                console.log(`  Gaps    : ${app.capabilityGapCount} unresolved`);
             if (typeof app.confirmedPolicyCount === "number")
                 console.log(`  Policy  : ${app.confirmedPolicyCount} confirmed`);
             if (app.requiresPolicyReview)

package/dist/commands/command-claim.js

@@ -2,6 +2,7 @@ import process from "process";
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { selectCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -36,6 +37,7 @@ export async function commandClaim(args) {
     const asJson = parseFlag(args, "--json");
     const id = parseOptionValue(args, "--id");
     const agentKeyArg = parseOptionValue(args, "--agent-ref") ?? parseOptionValue(args, "--agent-key");
+    const applicationEntityRef = parseOptionValue(args, "--application-ref");
     if (!id) {
         console.error("error: --id <commandId> is required");
         process.exit(1);
@@ -47,10 +49,13 @@ export async function commandClaim(args) {
         console.error("error: no agent key found. Pass --agent-key or run nexarch init-agent first.");
         process.exit(1);
     }
+    const lease = selectCheckInLease(creds.companyId, agentKey);
     const raw = await callMcpTool("nexarch_claim_command_by_id", {
         commandId: id,
         agentRef: agentKey,
         agentKey,
+        leaseToken: lease?.leaseToken,
+        applicationEntityRef: applicationEntityRef ?? undefined,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });
     const result = parseToolText(raw);
@@ -58,10 +63,19 @@ export async function commandClaim(args) {
         process.stdout.write(JSON.stringify(result) + "\n");
         return;
     }
+    if ((result.warnings ?? []).length > 0) {
+        for (const warning of result.warnings ?? []) {
+            if (warning.message)
+                console.log(`Warning: ${warning.message}`);
+        }
+        console.log("Tip: run `npx nexarch check-in` to refresh your lease before delivery actions.");
+    }
     if (!result.command) {
         console.log(`Command ${id} was not claimed.`);
         if (result.reason)
             console.log(`Reason: ${result.reason}`);
+        if (!applicationEntityRef)
+            console.log("Tip: re-run with --application-ref <application:key>.");
         return;
     }
     const cmd = result.command;

package/dist/commands/init-project.js

@@ -221,7 +221,7 @@ function choosePreferredRepositoryRef(candidates) {
     });
     return scored[0]?.rawRef ?? null;
 }
-function detectSourceRepository(dir) {
+export function detectSourceRepository(dir) {
     let rawRef = null;
     let vcsType = "unknown";
     // Prefer git when present, and prefer hosted remotes over local-only URLs.
@@ -869,7 +869,7 @@ function structuralRelForSubPackage(sp, projectExternalKey) {
         return { type: "part_of", from: sp.externalKey, to: projectExternalKey };
     return null;
 }
-function scanProject(dir) {
+export function scanProject(dir) {
     const names = new Set();
     let projectName = basename(dir);
     const subPackages = [];
@@ -995,7 +995,7 @@ function pickRelationshipType(toEntityTypeCode, toEntitySubtypeCode, _fromEntity
             return "depends_on";
     }
 }
-function normalizeToken(value) {
+export function normalizeToken(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
 }
 function extractHost(input) {
@@ -1008,7 +1008,7 @@ function extractHost(input) {
         return null;
     }
 }
-function scoreApplicationCandidate(app, projectName, repoUrl) {
+export function scoreApplicationCandidate(app, projectName, repoUrl) {
     const entityRef = app.entityRef ?? app.externalKey ?? null;
     if (!entityRef)
         return null;

package/dist/commands/proposals-start.js

@@ -1,7 +1,9 @@
 import process from "process";
 import * as readline from "node:readline/promises";
-import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
+import { selectCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -20,6 +22,18 @@ function parseToolText(result) {
     const text = result.content?.[0]?.text ?? "{}";
     return JSON.parse(text);
 }
+function loadIdentity() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return { agentKey: null };
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return { agentKey: data.agentKey ?? null };
+    }
+    catch {
+        return { agentKey: null };
+    }
+}
 function slugify(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "application";
 }
@@ -199,6 +213,8 @@ function inferStackTemplate(proposal) {
 function buildReadme(proposal, template) {
     const technologies = proposal.technologyChoices.map((item) => item.name);
     const policies = proposal.policyControls.map((item) => item.name);
+    const capabilityGaps = (proposal.proposal.recommendationCapabilityGaps ?? [])
+        .map((item) => `${item.capability ?? "Unspecified capability"}${item.layer ? ` (${item.layer})` : ""}${item.severity ? ` — ${item.severity}` : ""}${item.reason ? `: ${item.reason}` : ""}`);
     return `# ${proposal.application.name}
 
 ${proposal.application.description ?? "Application scaffold generated from a NexArch proposal."}
@@ -216,13 +232,14 @@ ${proposal.proposal.requiresPolicyReview ? `> Policy review is required before a
 - Workflow state: ${proposal.application.workflowState}
 - Application subtype: ${proposal.application.entitySubtypeCode ?? "Not specified"}
 - Recommendation basis: ${proposal.application.recommendationBasis ?? "Not specified"}
+- Recommendation status: ${proposal.application.recommendationStatus ?? proposal.proposal.recommendationStatus ?? "Not specified"}
 - NexArch reference: ${proposal.application.entityRef ?? proposal.application.id}
 
 ${proposal.application.recommendationSummary ? `## Recommendation notes\n\n${proposal.application.recommendationSummary}\n\n` : ""}## Suggested technology choices
 
 ${formatBulletList(technologies)}
 
-## Policy controls to satisfy
+${capabilityGaps.length > 0 ? `## Capability gaps\n\n${formatBulletList(capabilityGaps)}\n\n` : ""}## Policy controls to satisfy
 
 ${formatBulletList(policies)}
 
@@ -233,11 +250,20 @@ ${template.nextSteps.map((step, index) => `${index + 1}. ${step}`).join("\n")}
 }
 function buildProposalMarkdown(proposal) {
     const techLines = proposal.technologyChoices.map((tech) => `${tech.name}${tech.entitySubtypeCode ? ` (${tech.entitySubtypeCode})` : ""}${tech.description ? ` — ${tech.description}` : ""}`);
+    const recommendationDetailLines = (proposal.proposal.recommendationTechnologyDetails ?? [])
+        .map((tech) => `${tech.entityName ?? tech.entityId ?? "Unknown technology"}${tech.architectureLayer ? ` [${tech.architectureLayer}]` : ""}${tech.source ? ` • ${tech.source}` : ""}${tech.reason ? ` — ${tech.reason}` : ""}`);
+    const blueprintLines = (proposal.proposal.recommendationBlueprint ?? [])
+        .map((item) => `${item.label ?? item.layer ?? "Unlabelled layer"}${item.coverage ? ` — ${item.coverage}` : ""}${item.recommendationEntityIds.length > 0 ? ` (${item.recommendationEntityIds.length} mapped recommendation${item.recommendationEntityIds.length === 1 ? "" : "s"})` : ""}`);
+    const capabilityGapLines = (proposal.proposal.recommendationCapabilityGaps ?? [])
+        .map((item) => `${item.capability ?? "Unspecified capability"}${item.layer ? ` [${item.layer}]` : ""}${item.severity ? ` • ${item.severity}` : ""}${item.reason ? ` — ${item.reason}` : ""}`);
+    const warningLines = proposal.proposal.recommendationWarnings ?? [];
+    const riskLines = proposal.proposal.recommendationRisks ?? [];
     const policyLines = proposal.policyControls.map((control) => `${control.name}${control.description ? ` — ${control.description}` : ""}`);
     const gateLines = proposal.proposal.requiresPolicyReview
         ? `- Activation gate: policy review required\n- Required policy controls: ${proposal.proposal.requiredPolicyControlIds?.length ?? 0}\n`
         : "";
-    return `# NexArch proposal context\n\n## Application\n\n- Name: ${proposal.application.name}\n- ID: ${proposal.application.id}\n- Reference: ${proposal.application.entityRef ?? "n/a"}\n- Subtype: ${proposal.application.entitySubtypeCode ?? "n/a"}\n- Description: ${proposal.application.description ?? "n/a"}\n- Recommendation basis: ${proposal.application.recommendationBasis ?? "n/a"}\n- Proposal source: ${proposal.proposal.proposalSource ?? "n/a"}\n${gateLines}\n${proposal.application.recommendationSummary ? `## Recommendation summary\n\n${proposal.application.recommendationSummary}\n\n` : ""}${proposal.proposal.preScaffoldInstructions ? `## Pre-scaffold instruction\n\n${proposal.proposal.preScaffoldInstructions}\n\n` : ""}## Technology choices\n\n${formatBulletList(techLines)}\n\n## Policy controls\n\n${formatBulletList(policyLines)}\n`;
+    const trace = proposal.proposal.recommendationTrace;
+    return `# NexArch proposal context\n\n## Application\n\n- Name: ${proposal.application.name}\n- ID: ${proposal.application.id}\n- Reference: ${proposal.application.entityRef ?? "n/a"}\n- Subtype: ${proposal.application.entitySubtypeCode ?? "n/a"}\n- Description: ${proposal.application.description ?? "n/a"}\n- Recommendation basis: ${proposal.application.recommendationBasis ?? "n/a"}\n- Recommendation status: ${proposal.application.recommendationStatus ?? proposal.proposal.recommendationStatus ?? "n/a"}\n- Recommendation job: ${proposal.application.recommendationJobId ?? proposal.proposal.recommendationJobId ?? "n/a"}\n- Recommendation generated: ${proposal.application.recommendationGeneratedAt ?? proposal.proposal.recommendationGeneratedAt ?? "n/a"}\n- Proposal source: ${proposal.proposal.proposalSource ?? "n/a"}\n${gateLines}\n${proposal.application.recommendationSummary ? `## Recommendation summary\n\n${proposal.application.recommendationSummary}\n\n` : ""}${blueprintLines.length > 0 ? `## Layer blueprint\n\n${formatBulletList(blueprintLines)}\n\n` : ""}${recommendationDetailLines.length > 0 ? `## Recommendation provenance\n\n${formatBulletList(recommendationDetailLines)}\n\n` : ""}${capabilityGapLines.length > 0 ? `## Capability gaps\n\n${formatBulletList(capabilityGapLines)}\n\n` : ""}${warningLines.length > 0 ? `## Warnings\n\n${formatBulletList(warningLines)}\n\n` : ""}${riskLines.length > 0 ? `## Risks\n\n${formatBulletList(riskLines)}\n\n` : ""}${trace ? `## Recommendation trace\n\n- Candidate count: ${trace.candidateCount ?? 0}\n- Reference matches: ${trace.referenceMatchCount ?? 0}\n- Similar applications: ${trace.similarApplicationCount ?? 0}\n\n` : ""}${proposal.proposal.preScaffoldInstructions ? `## Pre-scaffold instruction\n\n${proposal.proposal.preScaffoldInstructions}\n\n` : ""}## Technology choices\n\n${formatBulletList(techLines)}\n\n## Policy controls\n\n${formatBulletList(policyLines)}\n`;
 }
 function buildPolicyMarkdown(proposal) {
     if (proposal.policyControls.length === 0) {
@@ -498,6 +524,9 @@ export async function proposalsStart(args) {
     const reason = parseOptionValue(args, "--reason") ?? "Application scaffold started from approved proposal workflow";
     const repoUrl = parseOptionValue(args, "--repo");
     const creds = requireCredentials();
+    const identity = loadIdentity();
+    const agentRef = identity.agentKey;
+    const lease = agentRef ? selectCheckInLease(creds.companyId, agentRef) : null;
     const listRaw = await callMcpTool("nexarch_list_proposed_applications", { companyId: creds.companyId }, { companyId: creds.companyId });
     const list = parseToolText(listRaw);
     const proposals = list.proposals ?? [];
@@ -567,8 +596,10 @@ export async function proposalsStart(args) {
                 initiatedBy: "nexarch-cli",
                 command: "proposals start",
                 operatorEmail: creds.email,
+                agentRef,
             },
             reviewedPolicyControlIds: proposal.proposal.requiredPolicyControlIds ?? proposal.proposal.confirmedPolicyControlIds,
+            leaseToken: lease?.leaseToken,
         }, { companyId: creds.companyId });
         activated = parseToolText(activateRaw);
     }
@@ -591,6 +622,10 @@ export async function proposalsStart(args) {
     console.log(`- Runtime : ${scaffold.template.runtime}`);
     console.log(`- Files   : ${scaffold.createdFiles.length} created`);
     console.log(`- State   : ${activated ? `${activated.status}${activated.alreadyActive ? " (already active)" : ""}` : "left in proposed state"}`);
+    for (const warning of activated?.warnings ?? []) {
+        if (warning.message)
+            console.log(`- Warning : ${warning.message}`);
+    }
     console.log("\nNext steps:");
     scaffold.template.nextSteps.forEach((step, index) => console.log(`${index + 1}. ${step}`));
     console.log(`${scaffold.template.nextSteps.length + 1}. Use docs/architecture/nexarch-proposal.md and policy-controls.md while building.`);

package/dist/commands/register-runtime.js

@@ -0,0 +1,77 @@
+import process from "process";
+import { existsSync, readFileSync } from "node:fs";
+import { arch, hostname, platform, release, type as osType, homedir } from "node:os";
+import { join } from "node:path";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+import { inferAccessibleApplicationRefs } from "../lib/application-context.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const value = args[idx + 1];
+    if (!value || value.startsWith("--"))
+        return null;
+    return value;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+function loadIdentity() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return { agentKey: null };
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return { agentKey: data.agentKey ?? null };
+    }
+    catch {
+        return { agentKey: null };
+    }
+}
+export async function registerRuntime(args) {
+    const asJson = parseFlag(args, "--json");
+    const applicationRefArg = parseOptionValue(args, "--application-ref");
+    const client = parseOptionValue(args, "--client") ?? "nexarch-cli";
+    const version = parseOptionValue(args, "--version") ?? null;
+    const mode = process.env.CI ? "ci" : "interactive";
+    const creds = requireCredentials();
+    const identity = loadIdentity();
+    if (!identity.agentKey)
+        throw new Error("No agent key found. Run nexarch init-agent first.");
+    const applicationContext = await inferAccessibleApplicationRefs({
+        companyId: creds.companyId,
+        explicitApplicationRefs: applicationRefArg ? [applicationRefArg] : undefined,
+    });
+    const raw = await callMcpTool("nexarch_register_agent_runtime", {
+        agentRef: identity.agentKey,
+        runtime: {
+            client,
+            ...(version ? { version } : {}),
+            mode,
+            nodeVersion: process.version,
+        },
+        host: {
+            hostname: hostname(),
+            osPlatform: platform(),
+            osType: osType(),
+            osRelease: release(),
+            arch: arch(),
+        },
+        applicationContext: applicationContext.accessibleApplicationRefs.length > 0
+            ? { accessibleApplicationRefs: applicationContext.accessibleApplicationRefs }
+            : undefined,
+        companyId: creds.companyId,
+    }, { companyId: creds.companyId });
+    const result = parseToolText(raw);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
+    console.log(`Registered runtime for ${identity.agentKey}.`);
+    console.log(`Application context: ${applicationContext.detail}`);
+}

package/dist/commands/setup.js

@@ -67,9 +67,9 @@ export async function setup(args) {
     if (clients.length > 0) {
         const names = clients.map((c) => c.name);
         const listed = names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
-        console.log(`\nSetup complete. Open a new ${listed} session and ask your agent to "register with Nexarch".`);
+        console.log(`\nSetup complete. Open a new ${listed} session and ask your agent to register its runtime with Nexarch. Check-in is a separate step when you want to preview work.`);
     }
     else {
-        console.log('\nSetup complete. Once you have configured an MCP client (see above), open a new session and ask your agent to "register with Nexarch".');
+        console.log("\nSetup complete. Once you have configured an MCP client (see above), open a new session and ask your agent to register its runtime with Nexarch. Check-in is a separate step when you want to preview work.");
     }
 }

package/dist/commands/status.js

@@ -1,3 +1,4 @@
+import { getCheckInLeaseState, loadCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { callMcpTool } from "../lib/mcp.js";
@@ -6,6 +7,8 @@ export async function status(_args) {
     const selectedCompanyId = creds.companyId;
     const expiresAt = new Date(creds.expiresAt);
     const daysLeft = Math.ceil((expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+    const lease = loadCheckInLease();
+    const leaseState = lease && lease.companyId === selectedCompanyId ? getCheckInLeaseState(lease) : { status: "missing", expiresInSeconds: null };
     process.stdout.write("Connecting to mcp.nexarch.ai… ");
     let governance;
     let registryInfo = null;
@@ -51,7 +54,19 @@ export async function status(_args) {
         console.log(`  Latest snapshot:     none published yet`);
     }
     console.log(`\n  Token expires:  ${expiresAt.toLocaleDateString()} (${daysLeft} days)`);
+    if (leaseState.status === "valid" && lease) {
+        console.log(`  Check-in lease: ${new Date(lease.leaseExpiresAt).toLocaleString()} (${Math.ceil((leaseState.expiresInSeconds ?? 0) / 3600)}h left)`);
+    }
+    else if (leaseState.status === "expired" && lease) {
+        console.log(`  Check-in lease: expired at ${new Date(lease.leaseExpiresAt).toLocaleString()}`);
+    }
+    else {
+        console.log("  Check-in lease: none stored");
+    }
     if (daysLeft <= 14) {
         console.log(`\n  ⚠  Your token expires soon. Run \`nexarch login\` to renew.`);
     }
+    if (leaseState.status !== "valid") {
+        console.log("  ⚠  Run `nexarch check-in` to refresh your workspace lease.");
+    }
 }

package/dist/index.js

@@ -25,6 +25,7 @@ import { policyAuditResults } from "./commands/policy-audit-results.js";
 import { appliedPolicies } from "./commands/applied-policies.js";
 import { governanceSummary } from "./commands/governance-summary.js";
 import { proposalsStart } from "./commands/proposals-start.js";
+import { registerRuntime } from "./commands/register-runtime.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -43,6 +44,7 @@ const commands = {
     "resolve-names": resolveNames,
     "list-entities": listEntities,
     "list-relationships": listRelationships,
+    "register-runtime": registerRuntime,
     "check-in": checkIn,
     "command-done": commandDone,
     "command-fail": commandFail,
@@ -180,12 +182,20 @@ Usage:
                                --to <toExternalKey>
                                --limit <1-500>
                                --json
+  nexarch register-runtime
+                      Register or refresh runtime + optional application context
+                      without performing check-in.
+                      Options: --application-ref <entityRef>
+                               --client <name>
+                               --version <semver>
+                               --json
   nexarch check-in    Preview pending application-target commands (no auto-claim)
                       and report draft/proposed applications needing review so the
                       agent can prompt the user to explore and instantiate them.
                       Use command-claim to explicitly claim a specific command.
                       Scope is resolved server-side from active company context.
                       Options: --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  narrow preview scope
                                --json              JSON output includes draftApplications[] and proposedApplications[]
   nexarch proposals start
                       Start a new application workspace from a proposed NexArch app.
@@ -205,6 +215,7 @@ Usage:
                       Explicitly claim a pending command by ID.
                       Options: --id <commandId>    (required)
                                --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  required for application-target commands
                                --json
   nexarch command-done
                       Mark a claimed command as completed.

package/dist/lib/application-context.js

@@ -0,0 +1,51 @@
+import { resolve as resolvePath } from "node:path";
+import { callMcpTool } from "./mcp.js";
+import { detectSourceRepository, scanProject, scoreApplicationCandidate } from "../commands/init-project.js";
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+export async function inferAccessibleApplicationRefs(params) {
+    const explicit = Array.from(new Set((params.explicitApplicationRefs ?? []).map((value) => value.trim()).filter(Boolean)));
+    if (explicit.length > 0) {
+        return {
+            accessibleApplicationRefs: explicit,
+            source: "explicit",
+            detail: `Using explicit application context (${explicit.join(", ")}).`,
+            repoUrl: detectSourceRepository(params.dir ?? process.cwd())?.url ?? null,
+            projectNames: [],
+            candidates: [],
+        };
+    }
+    const dir = resolvePath(params.dir ?? process.cwd());
+    const repoUrl = detectSourceRepository(dir)?.url ?? null;
+    const scan = scanProject(dir);
+    const projectNames = Array.from(new Set([scan.projectName, ...scan.subPackages.map((sp) => sp.name)])).filter(Boolean);
+    const appsRaw = await callMcpTool("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: params.companyId }, { companyId: params.companyId });
+    const appsData = parseToolText(appsRaw);
+    const apps = (appsData.entities ?? []).filter((entity) => (entity.entityRef ?? entity.externalKey));
+    const candidateMap = new Map();
+    for (const projectName of projectNames) {
+        for (const app of apps) {
+            const match = scoreApplicationCandidate(app, projectName, repoUrl);
+            if (!match)
+                continue;
+            const existing = candidateMap.get(match.entityRef);
+            if (!existing || match.score > existing.score) {
+                candidateMap.set(match.entityRef, match);
+            }
+        }
+    }
+    const candidates = Array.from(candidateMap.values()).sort((a, b) => b.score - a.score);
+    const accessibleApplicationRefs = candidates.filter((candidate) => candidate.score >= 0.85).map((candidate) => candidate.entityRef);
+    return {
+        accessibleApplicationRefs,
+        source: accessibleApplicationRefs.length > 0 ? "inferred" : "none",
+        detail: accessibleApplicationRefs.length > 0
+            ? `Inferred application context from current folder (${accessibleApplicationRefs.join(", ")}).`
+            : "No high-confidence application context inferred from current folder.",
+        repoUrl,
+        projectNames,
+        candidates,
+    };
+}

package/dist/lib/check-in-lease.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function leasePath() {
+    return join(homedir(), ".nexarch", "check-in-lease.json");
+}
+export function loadCheckInLease() {
+    const path = leasePath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const lease = JSON.parse(raw);
+        if (!lease.leaseToken || !lease.companyId || !lease.agentRef || !lease.leaseExpiresAt || !lease.leaseIssuedAt) {
+            return null;
+        }
+        return lease;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCheckInLease(lease) {
+    const dir = join(homedir(), ".nexarch");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(leasePath(), JSON.stringify(lease, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+export function clearCheckInLease() {
+    const path = leasePath();
+    if (existsSync(path))
+        rmSync(path);
+}
+export function selectCheckInLease(companyId, agentRef) {
+    const lease = loadCheckInLease();
+    if (!lease)
+        return null;
+    if (lease.companyId !== companyId)
+        return null;
+    if (lease.agentRef !== agentRef)
+        return null;
+    return lease;
+}
+export function getCheckInLeaseState(lease) {
+    if (!lease)
+        return { status: "missing", expiresInSeconds: null };
+    const expiresAtMs = new Date(lease.leaseExpiresAt).getTime();
+    const expiresInMs = expiresAtMs - Date.now();
+    if (!Number.isFinite(expiresAtMs) || expiresInMs <= 0) {
+        return { status: "expired", expiresInSeconds: 0 };
+    }
+    return { status: "valid", expiresInSeconds: Math.floor(expiresInMs / 1000) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.11.4",
+  "version": "0.12.1",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",