@gamaze/hicortex 0.17.6 → 0.18.0

package/dist/cli.js

@@ -18,7 +18,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const cli_args_js_1 = require("./cli-args.js");
-const command = process.argv[2];
+const command = (0, cli_args_js_1.resolveCommandAlias)(process.argv[2]);
 switch (command) {
     case "server": {
         const portArg = process.argv.indexOf("--port");
@@ -218,16 +218,19 @@ switch (command) {
         });
         break;
     }
-    case "context": {
-        // Standing context layer edit surface (spec §6): show|edit against the
-        // configured server. Secondary to the /context/ui Web UI; for headless boxes.
+    case "identity": {
+        // Standing identity layer edit surface (spec §6; renamed from context in
+        // 0.18 #264): show|edit against the configured server. Secondary to the
+        // /identity/ui Web UI; for headless boxes. The legacy `context` command is
+        // kept as a hidden backcompat alias via resolveCommandAlias so old scripts
+        // and muscle memory keep working.
         const args = process.argv.slice(3);
-        import("./context-cli.js").then(({ runContextCommand, ContextCliError }) => {
-            runContextCommand(args).catch((err) => {
-                if (err instanceof ContextCliError)
+        import("./identity-cli.js").then(({ runIdentityCommand, IdentityCliError }) => {
+            runIdentityCommand(args).catch((err) => {
+                if (err instanceof IdentityCliError)
                     console.error(err.message);
                 else
-                    console.error("[hicortex] context command failed:", err instanceof Error ? err.message : err);
+                    console.error("[hicortex] identity command failed:", err instanceof Error ? err.message : err);
                 process.exit(1);
             });
         });
@@ -271,12 +274,14 @@ switch (command) {
                 .catch(() => process.exit(0));
         }).catch(() => process.exit(0));
         break;
-    case "lessons-context":
-        // CC SessionStart hook: fetch lessons from the configured server and print
-        // a Markdown block to stdout. Fail-soft — any error = silent exit 0 so a
-        // broken hook never blocks a CC session.
-        import("./lessons-context.js").then(({ fetchLessonsContext }) => {
-            fetchLessonsContext()
+    case "learnings-identity": {
+        // CC SessionStart hook: fetch identity + lessons from the configured server
+        // and print a Markdown block to stdout. Canonical command name since #264;
+        // the legacy `lessons-context` subcommand is kept as a backcompat alias via
+        // resolveCommandAlias so existing installed hooks keep working. Fail-soft —
+        // any error = silent exit 0 so a broken hook never blocks a CC session.
+        import("./learnings-identity.js").then(({ fetchLessonsIdentity }) => {
+            fetchLessonsIdentity()
                 .then((block) => {
                 if (block)
                     process.stdout.write(block + "\n");
@@ -285,6 +290,7 @@ switch (command) {
                 .catch(() => process.exit(0));
         }).catch(() => process.exit(0));
         break;
+    }
     default:
         console.log(`Hicortex — Human-like memory for self-improving AI agents
 
@@ -296,7 +302,7 @@ Commands:
                   Scaffolds 5 editable default memory domains (Work, Personal,
                   People, Health, Finance) in ~/.hicortex/config.json
   init --server <url>  Set up as client (remote server)
-  init --agent-name <name>  Opt in to a per-agent context id (default: unset — shared global context)
+  init --agent-name <name>  Opt in to a per-agent identity id (default: unset — shared global identity)
                             Pass --agent-name "" to clear it back to global
   init --repair-config  Recover from a malformed ~/.hicortex/config.json: move it to
                         config.json.corrupt-<timestamp> and rebuild. Nothing is deleted.
@@ -306,9 +312,11 @@ Commands:
   dedup           Cluster + merge near-duplicate memories (server mode; dry run by default)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
   classify-types    Backfill episode→fact/decision type tags over the corpus (server mode)
-  lessons-context Fetch lessons and print Markdown to stdout (CC SessionStart hook)
+  learnings-identity  Fetch identity + lessons and print Markdown to stdout (CC SessionStart hook)
+                      (alias: lessons-context — the pre-#264 name, kept for backcompat)
   recall-hook    Pushed recall index for the current prompt (CC UserPromptSubmit/SessionStart hook)
-  context         Standing context layer (show|edit) against the configured server
+  identity        Standing identity layer (show|edit) against the configured server
+                  (alias: context — the pre-0.18 name, kept for backcompat)
   telemetry       Show exactly what anonymous telemetry sends (read-only)
   status          Show current configuration and stats
   uninstall       Remove CC integration (preserves DB)
@@ -333,9 +341,10 @@ Options:
   classify-types --all      Reclassify every memory (default: only episodes)
   classify-types --batch <n>  Memories per batch (default: 200)
   classify-types --reset    Restart from the beginning (ignore saved cursor)
-  context show [name]       Print all context sections, or just <name> (raw, pipeable)
-  context edit <name>       Edit a section in $EDITOR; PUT only if changed
-  context … --agent <id>    Target a per-agent scope instead of the global set
+  identity show [name]      Print all identity sections, or just <name> (raw, pipeable)
+  identity edit <name>      Edit a section in $EDITOR; PUT only if changed
+  identity … --agent <id>   Target a per-agent scope instead of the global set
+  (the legacy 'context' command remains as a hidden alias for 'identity')
 
 Examples:
   npx @gamaze/hicortex server

package/dist/consolidate.d.ts

@@ -63,6 +63,21 @@ export declare class BudgetTracker {
     maxCalls: number;
     callsUsed: number;
     callsByStage: Record<string, number>;
+    /**
+     * Per-stage count of LLM-call REQUESTS refused because the budget was
+     * exhausted (#255). Keys are the same stage labels passed to `use()`. The
+     * value is the SUM of the `count` args passed to each refused `use()` call
+     * in that stage (in production every `use()` call passes count=1, so each
+     * refused call adds 1 — but the API accepts a batch count, so a single
+     * refused batch request accrues its full count). Stages break on the first
+     * refusal, so a stage's value is the count of the one request that crossed
+     * the boundary. For item-level skip counts (how many memories or pairs were
+     * left unprocessed), see the per-stage reports — e.g.
+     * `stages.importance.skipped_budget` — which count MEMORIES, not call
+     * requests. Surfaced in summary() and ConsolidationReport as
+     * `deferred_by_stage`.
+     */
+    deferredByStage: Record<string, number>;
     /**
      * Token usage per stage (#246). Keys are the same stage labels passed to
      * `use()`. A stage that made no metered calls (no usage returned — never the

package/dist/consolidate.js

@@ -127,6 +127,21 @@ class BudgetTracker {
     maxCalls;
     callsUsed = 0;
     callsByStage = {};
+    /**
+     * Per-stage count of LLM-call REQUESTS refused because the budget was
+     * exhausted (#255). Keys are the same stage labels passed to `use()`. The
+     * value is the SUM of the `count` args passed to each refused `use()` call
+     * in that stage (in production every `use()` call passes count=1, so each
+     * refused call adds 1 — but the API accepts a batch count, so a single
+     * refused batch request accrues its full count). Stages break on the first
+     * refusal, so a stage's value is the count of the one request that crossed
+     * the boundary. For item-level skip counts (how many memories or pairs were
+     * left unprocessed), see the per-stage reports — e.g.
+     * `stages.importance.skipped_budget` — which count MEMORIES, not call
+     * requests. Surfaced in summary() and ConsolidationReport as
+     * `deferred_by_stage`.
+     */
+    deferredByStage = {};
     /**
      * Token usage per stage (#246). Keys are the same stage labels passed to
      * `use()`. A stage that made no metered calls (no usage returned — never the
@@ -151,8 +166,15 @@ class BudgetTracker {
     }
     use(stage, count = 1) {
         if (this.callsUsed + count > this.maxCalls) {
-            console.warn(`[hicortex] Budget exhausted: ${this.callsUsed}/${this.maxCalls} used, ` +
-                `requested ${count} more (stage: ${stage})`);
+            // #255: emit as a STRUCTURED event (not a bare prose warn) so a monitor
+            // can grep/parse `event=budget_exhausted` from journald. The line stays
+            // human-readable (key=value tokens after the [hicortex] prefix). Deferred
+            // counts are accrued BEFORE the log so the line reflects the up-to-date
+            // per-stage toll — the refused count is added to this stage's slot.
+            this.deferredByStage[stage] = (this.deferredByStage[stage] ?? 0) + count;
+            console.warn(`[hicortex] event=budget_exhausted stage=${stage} ` +
+                `calls_used=${this.callsUsed} max_calls=${this.maxCalls} ` +
+                `deferred_by_stage=${JSON.stringify(this.deferredByStage)}`);
             return false;
         }
         this.callsUsed += count;
@@ -183,6 +205,11 @@ class BudgetTracker {
             calls_used: this.callsUsed,
             calls_remaining: this.remaining,
             calls_by_stage: { ...this.callsByStage },
+            // #255: exhaustion + per-stage deferred counts flow into the report →
+            // telemetry + dashboard. Always present (post-#255); absent implies a
+            // pre-#255 report (treat as false / no deferrals).
+            exhausted: this.exhausted,
+            deferred_by_stage: { ...this.deferredByStage },
             tokens_by_stage: Object.fromEntries(Object.entries(this.tokensByStage).map(([k, v]) => [k, { ...v }])),
             tokens_total: { ...this.totalTokens },
         };
@@ -393,7 +420,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             const sourcePattern = String(lo.source_pattern ?? "");
             // No `## Lesson:` prefix: memory_type='lesson' carries the type, and the
             // text is the topic-first first line (display reads the first line, not a
-            // header parse — see lessons-context.ts / index.ts).
+            // header parse — see learnings-identity.ts / index.ts).
             let content = `${lessonText}\n\n`;
             content += `**Type:** ${lessonType}\n`;
             content += `**Severity:** ${severity}\n`;

package/dist/dashboard.d.ts

@@ -53,6 +53,32 @@ export interface DashboardMetrics {
             completion: number;
             total: number;
         }>;
+        /**
+         * Always-on consolidation-budget usage metric (#255 CR). `calls_used` is
+         * how many LLM calls the run actually spent; `max_calls` is the configured
+         * `consolidateMaxLlmCalls` ceiling. Forwarded whenever consolidation ran
+         * (the digest renders a continuous used/max bar, like the token-usage
+         * metric, so you can see the budget climbing before exhaustion). Undefined
+         * on backfill rows and on runs where consolidation didn't execute
+         * (capture-only / no_llm / throttled / skipped) — the page renders no bar.
+         */
+        budget_calls_used?: number;
+        budget_max_calls?: number;
+        /**
+         * True when this run's consolidation budget (`consolidateMaxLlmCalls`)
+         * was exhausted — LLM-bound stages deferred remaining work (#255).
+         * Forwarded ONLY on exhaustion (the alert state on top of the always-on
+         * usage bar). Undefined on healthy runs (where budget_calls_used is still
+         * present), backfill rows, and non-run nights.
+         */
+        budget_exhausted?: boolean;
+        /**
+         * Per-stage count of refused LLM-call requests on an exhausted run (#255).
+         * Mirrors ConsolidationReport.budget.deferred_by_stage. Forwarded in
+         * lockstep with `budget_exhausted` (exhausted runs only) so the snapshot
+         * shape is clean on healthy runs.
+         */
+        budget_deferred_by_stage?: Record<string, number>;
     };
     /** Corpus capacity (#245). `memory_soft_cap` is the configured ceiling (0 =
      *  disabled); always present in real snapshots, undefined on backfilled
@@ -131,6 +157,17 @@ export interface DashboardData {
                 completion: number;
                 total: number;
             }>;
+            /**
+             * Always-on consolidation-budget usage (#255 CR). Present whenever the
+             * day's snapshot carries them (consolidation ran). The page renders a
+             * used/max bar in the same style as the token-usage metric.
+             */
+            budget_calls_used?: number;
+            budget_max_calls?: number;
+            /** True when the run exhausted its consolidation budget (#255). */
+            budget_exhausted?: boolean;
+            /** Per-stage refused-request counts on an exhausted run (#255). */
+            budget_deferred_by_stage?: Record<string, number>;
         };
         dedup_merges: {
             loser_id: string;
@@ -170,6 +207,26 @@ export interface NightlyDelta {
         completion: number;
         total: number;
     }>;
+    /**
+     * Always-on consolidation-budget usage (#255 CR). Forwarded whenever
+     * consolidation ran so the dashboard renders a continuous used/max bar.
+     * `callsUsed` = LLM calls spent this run; `maxCalls` = configured ceiling.
+     * Undefined in lockstep (both set together when consolidation ran).
+     */
+    budgetCallsUsed?: number;
+    budgetMaxCalls?: number;
+    /**
+     * True when this run's consolidation budget was exhausted (#255) — same as
+     * ConsolidationReport.budget.exhausted. Undefined when consolidation didn't
+     * run (capture-only / no_llm / throttled / skipped) or didn't exhaust.
+     */
+    budgetExhausted?: boolean;
+    /**
+     * Per-stage refused-request counts on an exhausted run (#255) — same shape
+     * as ConsolidationReport.budget.deferred_by_stage. Undefined in lockstep
+     * with `budgetExhausted`.
+     */
+    budgetDeferredByStage?: Record<string, number>;
 }
 /**
  * Write one snapshot row for `runAt` (an ISO timestamp the caller chooses —
@@ -225,7 +282,7 @@ export declare function handleDashboardData(db: Database.Database, query: {
 };
 /**
  * Express adapter for GET /dashboard/data. Wraps the pure handler so the
- * route stays thin (same convention as context-store handlers in viz.ts).
+ * route stays thin (same convention as identity-store handlers in viz.ts).
  * Failures surface as a 500 with the usual {error} shape — no silent degrade.
  */
 export declare function dashboardDataHandler(getDb: () => Database.Database, getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;

package/dist/dashboard.js

@@ -103,6 +103,24 @@ function writeSnapshot(db, runAt, delta, memorySoftCap) {
         // page treats undefined as "no data for this day", matching adoption.
         ...(delta.tokensThisRun !== undefined ? { tokens: delta.tokensThisRun } : {}),
         ...(delta.tokensByStage !== undefined ? { tokens_by_stage: delta.tokensByStage } : {}),
+        // #255 CR: always-on usage metric — forward calls_used + max_calls
+        // whenever consolidation ran (regardless of exhaustion) so the page can
+        // render a continuous used/max bar. Presence = a run happened; absence =
+        // consolidation didn't execute (capture-only / no_llm / throttled / skipped).
+        ...(delta.budgetCallsUsed !== undefined ? { budget_calls_used: delta.budgetCallsUsed } : {}),
+        ...(delta.budgetMaxCalls !== undefined ? { budget_max_calls: delta.budgetMaxCalls } : {}),
+        // #255: the alert state. budget_exhausted + budget_deferred_by_stage are
+        // gated on the SAME condition (exhausted=true) so the snapshot shape is
+        // clean on healthy runs — no empty {} leaking through (W4). The healthy
+        // signal is carried by budget_calls_used above, not by a false flag here.
+        ...(delta.budgetExhausted
+            ? {
+                budget_exhausted: true,
+                ...(delta.budgetDeferredByStage !== undefined
+                    ? { budget_deferred_by_stage: delta.budgetDeferredByStage }
+                    : {}),
+            }
+            : {}),
     };
     if (memorySoftCap !== undefined) {
         metrics.capacity = { memory_soft_cap: memorySoftCap };
@@ -404,6 +422,14 @@ function handleDashboardData(db, query, config) {
             // are forwarded together — the page renders either the breakdown or nothing.
             tokens: dayMetrics?.new_this_run?.tokens,
             tokens_by_stage: dayMetrics?.new_this_run?.tokens_by_stage,
+            // #255 CR: always-on usage metric — present whenever consolidation ran
+            // (under-cap OR exhausted). The page renders a continuous used/max bar.
+            budget_calls_used: dayMetrics?.new_this_run?.budget_calls_used,
+            budget_max_calls: dayMetrics?.new_this_run?.budget_max_calls,
+            // #255: budget exhaustion — only present when the run actually hit the
+            // cap (undefined on backfill / non-run / under-cap nights).
+            budget_exhausted: dayMetrics?.new_this_run?.budget_exhausted,
+            budget_deferred_by_stage: dayMetrics?.new_this_run?.budget_deferred_by_stage,
         },
         dedup_merges: dedupRows.map((r) => ({
             loser_id: r.loser_id,
@@ -429,7 +455,7 @@ function handleDashboardData(db, query, config) {
 }
 /**
  * Express adapter for GET /dashboard/data. Wraps the pure handler so the
- * route stays thin (same convention as context-store handlers in viz.ts).
+ * route stays thin (same convention as identity-store handlers in viz.ts).
  * Failures surface as a 500 with the usual {error} shape — no silent degrade.
  */
 function dashboardDataHandler(getDb, getConfig) {

package/dist/extensions.d.ts

@@ -7,7 +7,7 @@
  * still be swapped in (tests, future experiments).
  *
  *   LessonSelector — lesson selection sites:
- *     lessons-context.ts:fetchLessonsContext (CC SessionStart hook),
+ *     learnings-identity.ts:fetchLessonsIdentity (CC SessionStart hook),
  *     index.ts:before_agent_start (OC in-process plugin).
  *     The default is the domain-aware scoring selector (lesson-selection.ts):
  *     ranks lessons by project match + domain affinity + recency +

package/dist/extensions.js

@@ -8,7 +8,7 @@
  * still be swapped in (tests, future experiments).
  *
  *   LessonSelector — lesson selection sites:
- *     lessons-context.ts:fetchLessonsContext (CC SessionStart hook),
+ *     learnings-identity.ts:fetchLessonsIdentity (CC SessionStart hook),
  *     index.ts:before_agent_start (OC in-process plugin).
  *     The default is the domain-aware scoring selector (lesson-selection.ts):
  *     ranks lessons by project match + domain affinity + recency +

package/dist/health.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Health-endpoint + REST error-sanitisation helpers (#253).
+ *
+ * Two concerns live here:
+ *
+ * 1. The public `GET /health` probe is UNAUTHENTICATED and was previously
+ *    echoing tenant/install business-intelligence (memory count, link count,
+ *    DB size, version, the full LLM backend string) plus running `COUNT(*)`
+ *    on every hit. The public response is now just `{status:"ok"}`. The
+ *    diagnostics moved to `GET /health/detail`, which goes through the normal
+ *    bearer-token auth middleware (localhost bypasses as usual) so an
+ *    operator running `hicortex status` on the server box, or a co-located
+ *    nightly preflight, still gets them — but a remote/anonymous caller does
+ *    not. Spec: `specs/2026-07-27-hosted-service.md` §6, Phase 0a item 5a/b.
+ *
+ * 2. REST `res.status(500).json({error: err.message})` sites were echoing
+ *    internal detail (LLM upstream URLs, hostnames, stack frames) to the HTTP
+ *    caller. `logAndSendInternalError` logs the full detail server-side and
+ *    returns a generic `{error:"Internal error"}` body. Validation errors
+ *    (400 with a useful, non-leaking message) stay specific at their call
+ *    sites — only the catch blocks that could leak infrastructure route
+ *    through here.
+ */
+/**
+ * Public, unauthenticated health probe. Carries NO data — just liveness.
+ * Anyone hitting `/health` (load balancer, watchdog, anonymous prober) gets
+ * this and nothing else.
+ */
+export declare function publicHealthResponse(): {
+    status: "ok";
+};
+/**
+ * Operator-only diagnostics. Returned by `GET /health/detail` behind the
+ * standard auth middleware (localhost bypasses auth, so co-located tooling
+ * — `hicortex status`, nightly preflight, `init` detect — sees it without a
+ * token; a remote caller needs the bearer token).
+ */
+export declare function detailedHealthResponse(opts: {
+    memories: number;
+    links: number;
+    dbSizeBytes: number;
+    version: string;
+    llmLabel: string;
+}): {
+    status: "ok";
+    version: string;
+    memories: number;
+    links: number;
+    db_size_kb: number;
+    llm: string;
+};
+/**
+ * Log the full internal error detail server-side and return a generic
+ * client-facing 500 body. Use this in every REST catch block whose
+ * `err.message` could leak infrastructure (LLM upstream URLs, hostnames,
+ * stack frames, DB paths). Validation errors (400) with a useful,
+ * non-leaking message stay inline at the call site — this is for the
+ * catch-all 500 paths only.
+ *
+ * The `route` arg (e.g. "lessons", "distill") scopes the log line so an
+ * operator can tell which endpoint failed without the response body
+ * carrying that detail to the caller.
+ */
+export declare function logAndSendInternalError(res: {
+    status(code: number): {
+        json(body: unknown): void;
+    };
+}, route: string, err: unknown): void;

package/dist/health.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Health-endpoint + REST error-sanitisation helpers (#253).
+ *
+ * Two concerns live here:
+ *
+ * 1. The public `GET /health` probe is UNAUTHENTICATED and was previously
+ *    echoing tenant/install business-intelligence (memory count, link count,
+ *    DB size, version, the full LLM backend string) plus running `COUNT(*)`
+ *    on every hit. The public response is now just `{status:"ok"}`. The
+ *    diagnostics moved to `GET /health/detail`, which goes through the normal
+ *    bearer-token auth middleware (localhost bypasses as usual) so an
+ *    operator running `hicortex status` on the server box, or a co-located
+ *    nightly preflight, still gets them — but a remote/anonymous caller does
+ *    not. Spec: `specs/2026-07-27-hosted-service.md` §6, Phase 0a item 5a/b.
+ *
+ * 2. REST `res.status(500).json({error: err.message})` sites were echoing
+ *    internal detail (LLM upstream URLs, hostnames, stack frames) to the HTTP
+ *    caller. `logAndSendInternalError` logs the full detail server-side and
+ *    returns a generic `{error:"Internal error"}` body. Validation errors
+ *    (400 with a useful, non-leaking message) stay specific at their call
+ *    sites — only the catch blocks that could leak infrastructure route
+ *    through here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publicHealthResponse = publicHealthResponse;
+exports.detailedHealthResponse = detailedHealthResponse;
+exports.logAndSendInternalError = logAndSendInternalError;
+/**
+ * Public, unauthenticated health probe. Carries NO data — just liveness.
+ * Anyone hitting `/health` (load balancer, watchdog, anonymous prober) gets
+ * this and nothing else.
+ */
+function publicHealthResponse() {
+    return { status: "ok" };
+}
+/**
+ * Operator-only diagnostics. Returned by `GET /health/detail` behind the
+ * standard auth middleware (localhost bypasses auth, so co-located tooling
+ * — `hicortex status`, nightly preflight, `init` detect — sees it without a
+ * token; a remote caller needs the bearer token).
+ */
+function detailedHealthResponse(opts) {
+    return {
+        status: "ok",
+        version: opts.version,
+        memories: opts.memories,
+        links: opts.links,
+        db_size_kb: Math.round(opts.dbSizeBytes / 1024),
+        llm: opts.llmLabel,
+    };
+}
+/**
+ * Log the full internal error detail server-side and return a generic
+ * client-facing 500 body. Use this in every REST catch block whose
+ * `err.message` could leak infrastructure (LLM upstream URLs, hostnames,
+ * stack frames, DB paths). Validation errors (400) with a useful,
+ * non-leaking message stay inline at the call site — this is for the
+ * catch-all 500 paths only.
+ *
+ * The `route` arg (e.g. "lessons", "distill") scopes the log line so an
+ * operator can tell which endpoint failed without the response body
+ * carrying that detail to the caller.
+ */
+function logAndSendInternalError(res, route, err) {
+    // Stack when available (most informative), else name+message for Errors,
+    // else String(). NEVER echo this to the response body.
+    const detail = err instanceof Error
+        ? (err.stack ?? `${err.name}: ${err.message}`)
+        : String(err);
+    console.error(`[hicortex] /${route}: ${detail}`);
+    res.status(500).json({ error: "Internal error" });
+}

package/dist/identity-cli.d.ts

@@ -0,0 +1,90 @@
+/**
+ * identity-cli — `hicortex identity show|edit`, the secondary/headless edit
+ * surface for the standing identity layer (spec 2026-07-12 §6; renamed 0.18
+ * #264 from `context`). The Web UI (`/identity/ui`) is primary; this exists
+ * for boxes without a browser.
+ *
+ *   hicortex identity show [name]   GET /identity → print all sections, or one
+ *   hicortex identity edit <name>   GET section → $EDITOR → PUT if changed
+ *
+ * The legacy `hicortex context ...` command remains as a hidden alias so old
+ * scripts and muscle memory keep working (#264 backcompat).
+ *
+ * URL/token resolution mirrors learnings-identity.ts:44-49 (client mode →
+ * config.serverUrl; server mode → http://127.0.0.1:<port>; token from
+ * config.authToken) — explicitly NOT the hardcoded 127.0.0.1:8787 of
+ * status.ts. Fails soft with a clear message + non-zero exit on any server
+ * error, distinguishing a down server from an HTTP error (esp. 404 = server
+ * too old / wrong endpoint), like the OC plugin's describeGetFailure.
+ *
+ * The CLI targets the new `/identity` endpoint. A 0.18+ server (this package)
+ * also keeps `/context` as an alias, so a new CLI against a not-yet-upgraded
+ * server falls back through that alias via describeFailure's 404 hint.
+ */
+/** Thrown for any expected, user-facing failure. cli.ts prints .message + exits 1. */
+export declare class IdentityCliError extends Error {
+}
+/** Backcompat alias (#264). */
+export declare const ContextCliError: typeof IdentityCliError;
+export interface IdentityServerTarget {
+    baseUrl: string;
+    authToken?: string;
+}
+/**
+ * Resolve the server URL + token from a parsed config object. Pure + exported
+ * so it is unit-testable without a live config. Follows learnings-identity.ts.
+ */
+export declare function resolveIdentityTarget(config: Record<string, unknown>): IdentityServerTarget;
+/** Backcompat alias (#264). */
+export declare const resolveContextTarget: typeof resolveIdentityTarget;
+/** Backcompat alias (#264). */
+export type ContextServerTarget = IdentityServerTarget;
+/** Read ~/.hicortex/config.json (or $HICORTEX_HOME/config.json). Missing → {}. */
+export declare function loadConfig(): Record<string, unknown>;
+/** The Save decision: PUT only when the edited content differs. Pure + tested. */
+export declare function sectionChanged(before: string, after: string): boolean;
+export interface IdentityGetResponse {
+    sections: Record<string, string>;
+    updated_at: string | null;
+    clients: string[];
+    /** Present only for an agent-scoped read (0.13). */
+    agent?: string;
+    mode?: string;
+}
+/** Backcompat alias (#264). */
+export type ContextGetResponse = IdentityGetResponse;
+/** GET /identity. Throws IdentityCliError with a clear message on any failure. */
+export declare function getIdentity(target: IdentityServerTarget, agent?: string): Promise<IdentityGetResponse>;
+/** Backcompat alias (#264). */
+export declare const getContext: typeof getIdentity;
+/** PUT one section. Throws IdentityCliError with a clear message on any failure. */
+export declare function putSection(target: IdentityServerTarget, name: string, content: string, agent?: string): Promise<void>;
+/** Readable rendering of every section + the resolved clients line (show, no name). */
+export declare function formatAllSections(data: IdentityGetResponse): string;
+/** Raw markdown for one section (show <name>), or null if it does not exist. */
+export declare function formatOneSection(data: IdentityGetResponse, name: string): string | null;
+/**
+ * Default editor spawn: opens `file` in the first available editor, blocking
+ * until it exits. Returns true if an editor ran, false if none was found.
+ * Injectable so tests never actually spawn an editor.
+ */
+export type EditorSpawn = (file: string) => boolean;
+/**
+ * `edit <name>`: validate name (fast-fail; the server enforces too) → fetch
+ * current content → $EDITOR on a temp file → PUT only if changed. Temp file is
+ * always cleaned up. `spawn` is injectable for tests.
+ */
+export declare function runEdit(name: string, spawn?: EditorSpawn, agent?: string): Promise<void>;
+/**
+ * Split out a `--agent <id>` flag (anywhere in argv) from the positional args.
+ * The flag omitted → the global scope.
+ */
+export declare function extractAgentFlag(args: string[]): {
+    agent?: string;
+    rest: string[];
+};
+/** Dispatch for `hicortex identity <sub>` (and the hidden `context` alias).
+ *  Throws IdentityCliError on bad usage/failure. */
+export declare function runIdentityCommand(args: string[]): Promise<void>;
+/** Backcompat alias (#264). */
+export declare const runContextCommand: typeof runIdentityCommand;