@entelligentsia/forgecli 0.7.9 → 0.7.10

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.10] — 2026-05-17
+
+### Fixed
+- **FORGE-BUG-036 (critical):** Bundled `dist/forge-payload/tools/lib/`
+  now includes `suggest.cjs`. Without it, every invocation of the bundled
+  `store-cli.cjs` crashed with `Error: Cannot find module './suggest.cjs'`
+  because `validate.js` requires it. Root cause: `LIB_ALLOWLIST` in
+  `scripts/build-payload.cjs` was not updated when FORGE-S22-T03 added the
+  suggest module. All store operations (read/write/emit/update-status) from
+  forge-cli now work; agents no longer have to fall back to manual JSON
+  writes that bypass schema validation.
+- **bundledVersion alignment.** `package.json` `forge.bundledVersion` now
+  reports `0.43.19` (matches actual bundled plugin source).
+
+### Added
+- **Regression test** `test/extensions/forgecli/bug-036-payload-lib-completeness.test.ts`
+  walks every `require('./X')` in bundled `tools/lib/` and asserts each target
+  exists in the bundle. Catches future LIB_ALLOWLIST omissions on every build.
+
 ## [0.7.9] — 2026-05-17
 
 ### Added

package/dist/CHANGELOG-forge-plugin.md

@@ -5,6 +5,32 @@ Format: newest first. Breaking changes are marked **△ Breaking**.
 
 ---
 
+## [0.43.19] — 2026-05-17
+
+**G7 — Emit FK-check + reserved-prefix carve-out + orphan event-dir flagger.**
+
+### Added
+
+- `store-cli emit` — foreign-key check on `sprintId` arg. Rejects bare/unknown IDs
+  (e.g. `S01` instead of `FORGE-S01`) with structured error message including
+  `Unknown sprintId: <X>` + "Did you mean?" suggestion using Levenshtein + suffix
+  matching from `lib/suggest.cjs`.
+  Valid IDs = directory listing of `.forge/store/sprints/` + reserved `SYS-*` prefix.
+- `store-cli emit --allow-synthetic` — new flag bypasses the FK check for synthetic
+  or test-harness events. Documented in `--help`.
+- Reserved-prefix carve-out: any `SYS-*` pattern is accepted unconditionally
+  (system-generated events that predate sprint records).
+- `validate-store` Pass 2b — scans `.forge/store/events/` for subdirectories whose
+  name is not a known sprintId and does not match `SYS-*`. Flags each as
+  `ORPHAN_EVENT_DIR` warning (category preserved in `--json` mode). No auto-delete.
+
+### Tests
+
+All `node --test forge/tools/__tests__/*.test.cjs` pass (1302 tests). New FK-check
+cases in `store-cli.test.cjs`; new orphan-dir cases in `validate-store.test.cjs`.
+
+---
+
 ## [0.43.16] — 2026-05-15
 
 **Sprint finalization ceremony (Plan 12).** Pairs with forge-cli `v0.6.6`.

package/dist/bin/argv.d.ts

@@ -1,5 +1,5 @@
-/** Parsed result when `--version`, `--help`, or a fast-path subcommand is requested. */
-export type ForgeAction = "version" | "help" | "subcommand" | null;
+/** Parsed result when `--version`, `--help`, `doctor`, or a fast-path subcommand is requested. */
+export type ForgeAction = "version" | "help" | "doctor" | "subcommand" | null;
 /**
  * Whitelist of bare subcommands that bypass pi and exec a bundled cjs tool
  * directly. Each entry maps the user-typed subcommand to the cjs filename

package/dist/bin/argv.js

@@ -115,13 +115,22 @@ export function parseForgeArgv(argv) {
             }
             continue;
         }
+        // ── `forge doctor` — preflight onboarding check ─────────────────────
+        // Probes pi auth/model state via the exported APIs. Only matches the
+        // first bare token, no flags collected yet.
+        if (token === "doctor" && piArgv.length === 0) {
+            return {
+                forgeAction: "doctor",
+                piArgv: [],
+                env,
+                subcommandArgs: argv.slice(i + 1),
+            };
+        }
         // ── Fast-path subcommand (forge store, forge collate, etc.) ──────────
         // Only matches the FIRST bare token, and only when no flags have
         // been collected yet (so `forge --cwd /tmp store ...` still treats
         // `store` as a fast-path; forgeAction overrides piArgv in that case).
-        if (!token.startsWith("-") &&
-            Object.hasOwn(FAST_PATH_SUBCOMMANDS, token) &&
-            piArgv.length === 0) {
+        if (!token.startsWith("-") && Object.hasOwn(FAST_PATH_SUBCOMMANDS, token) && piArgv.length === 0) {
             return {
                 forgeAction: "subcommand",
                 piArgv: [],

package/dist/bin/argv.js.map

@@ -1 +1 @@
-{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../src/bin/argv.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../src/bin/argv.ts"],"names":[],"mappings":"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"}

package/dist/bin/doctor.d.ts

@@ -0,0 +1,59 @@
+export interface DoctorReport {
+    forgeCli: string;
+    forgePlugin: string;
+    pi: string;
+    cwd: string;
+    agentDir: string;
+    auth: {
+        stored: string[];
+        configured: string[];
+    };
+    models: {
+        total: number;
+        available: number;
+        samples: {
+            provider: string;
+            id: string;
+        }[];
+    };
+    settings: {
+        defaultProvider: string | undefined;
+        defaultModel: string | undefined;
+    };
+    migrations: {
+        performed: string[];
+        deprecationWarnings: string[];
+    };
+    status: "ready" | "no-credentials" | "no-models";
+    guidance?: string;
+}
+export interface DoctorVersions {
+    forgeCli: string;
+    forgePlugin: string;
+    pi: string;
+}
+/**
+ * Run the doctor probe. Returns a structured report.
+ *
+ * Side effects: runs pi's `runMigrations(cwd)` — this is the same call pi
+ * makes at startup, so doctor produces the same view pi would see. Without
+ * it, users who only ever set `ANTHROPIC_API_KEY` would appear as having
+ * no stored credentials, even though pi itself would migrate them on first
+ * launch.
+ */
+export declare function runDoctorProbe(versions: DoctorVersions, cwd?: string): Promise<DoctorReport>;
+/** Format a doctor report for human reading. */
+export declare function formatDoctorReport(r: DoctorReport): string;
+export interface DoctorOptions {
+    json: boolean;
+}
+export declare function parseDoctorArgs(args: readonly string[]): DoctorOptions | {
+    error: string;
+};
+/**
+ * Entry point invoked from `bin/forge.ts`. Returns the process exit code.
+ *
+ * Exit code: 0 when status === "ready", else 1 — matches pi's own
+ * non-interactive `formatNoModelsAvailableMessage` exit semantics.
+ */
+export declare function runDoctor(args: readonly string[], versions: DoctorVersions): Promise<number>;

package/dist/bin/doctor.js

@@ -0,0 +1,149 @@
+// forge doctor — preflight onboarding check.
+//
+// Reproduces pi's own startup auth/model probe using the exported APIs
+// (runMigrations, AuthStorage, ModelRegistry, SettingsManager) so the
+// user sees the same view forge will see when it later spawns pi
+// non-interactively. Quotes pi's canonical guidance strings verbatim so
+// the message matches what `pi -p` would print on a no-model exit.
+//
+// Iron-Law boundary: doctor PROBES via pi exports and FORWARDS to pi's
+// `/login` / docs. It must not reimplement login, model resolution, or
+// auth migration.
+import { AuthStorage, formatNoModelsAvailableMessage, getAgentDir, getProviderLoginHelp, ModelRegistry, runMigrations, SettingsManager, } from "@earendil-works/pi-coding-agent";
+/**
+ * Run the doctor probe. Returns a structured report.
+ *
+ * Side effects: runs pi's `runMigrations(cwd)` — this is the same call pi
+ * makes at startup, so doctor produces the same view pi would see. Without
+ * it, users who only ever set `ANTHROPIC_API_KEY` would appear as having
+ * no stored credentials, even though pi itself would migrate them on first
+ * launch.
+ */
+export async function runDoctorProbe(versions, cwd = process.cwd()) {
+    const { migratedAuthProviders, deprecationWarnings } = runMigrations(cwd);
+    const authStorage = AuthStorage.create();
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(cwd, agentDir);
+    const modelRegistry = ModelRegistry.create(authStorage);
+    const stored = authStorage.list();
+    const all = modelRegistry.getAll();
+    const available = modelRegistry.getAvailable();
+    const configuredProviders = Array.from(new Set(available.map((m) => m.provider))).sort();
+    const status = available.length > 0 ? "ready" : stored.length > 0 ? "no-models" : "no-credentials";
+    const report = {
+        forgeCli: versions.forgeCli,
+        forgePlugin: versions.forgePlugin,
+        pi: versions.pi,
+        cwd,
+        agentDir,
+        auth: {
+            stored,
+            configured: configuredProviders,
+        },
+        models: {
+            total: all.length,
+            available: available.length,
+            samples: available.slice(0, 5).map((m) => ({ provider: m.provider, id: m.id })),
+        },
+        settings: {
+            defaultProvider: settingsManager.getDefaultProvider(),
+            defaultModel: settingsManager.getDefaultModel(),
+        },
+        migrations: {
+            performed: migratedAuthProviders,
+            deprecationWarnings,
+        },
+        status,
+    };
+    if (status !== "ready") {
+        report.guidance =
+            status === "no-credentials"
+                ? `${formatNoModelsAvailableMessage()}\n\nRun \`pi\` once, log in with \`/login\`, then re-run forge.`
+                : `${getProviderLoginHelp()}\n\nStored providers found (${stored.join(", ")}), but no usable model. Open \`pi\` and pick a model with \`/model\`.`;
+    }
+    return report;
+}
+/** Format a doctor report for human reading. */
+export function formatDoctorReport(r) {
+    const lines = [];
+    lines.push("forge doctor");
+    lines.push("============");
+    lines.push(`forge-cli@${r.forgeCli}  forge-plugin@${r.forgePlugin}  pi@${r.pi}`);
+    lines.push("");
+    lines.push(`cwd: ${r.cwd}`);
+    lines.push(`pi agent dir: ${r.agentDir}`);
+    lines.push("");
+    lines.push("Auth:");
+    if (r.auth.stored.length === 0) {
+        lines.push("  (no providers in auth.json)");
+    }
+    else {
+        for (const p of r.auth.stored)
+            lines.push(`  ✓ ${p} (stored)`);
+    }
+    const envOnly = r.auth.configured.filter((p) => !r.auth.stored.includes(p));
+    for (const p of envOnly)
+        lines.push(`  ✓ ${p} (environment / runtime)`);
+    lines.push("");
+    lines.push(`Models: ${r.models.available}/${r.models.total} have auth configured`);
+    for (const m of r.models.samples)
+        lines.push(`  • ${m.provider}/${m.id}`);
+    if (r.models.available > r.models.samples.length) {
+        lines.push(`  … ${r.models.available - r.models.samples.length} more`);
+    }
+    lines.push("");
+    lines.push("Settings:");
+    lines.push(`  default provider: ${r.settings.defaultProvider ?? "(unset)"}`);
+    lines.push(`  default model:    ${r.settings.defaultModel ?? "(unset)"}`);
+    lines.push("");
+    if (r.migrations.performed.length > 0) {
+        lines.push(`Migrations performed: ${r.migrations.performed.join(", ")}`);
+    }
+    if (r.migrations.deprecationWarnings.length > 0) {
+        lines.push("Deprecation warnings:");
+        for (const w of r.migrations.deprecationWarnings)
+            lines.push(`  ⚠ ${w}`);
+    }
+    if (r.migrations.performed.length > 0 || r.migrations.deprecationWarnings.length > 0) {
+        lines.push("");
+    }
+    lines.push(`Status: ${r.status.toUpperCase()}`);
+    if (r.guidance) {
+        lines.push("");
+        lines.push(r.guidance);
+    }
+    return lines.join("\n");
+}
+export function parseDoctorArgs(args) {
+    let json = false;
+    for (const arg of args) {
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        return { error: `forge doctor: unknown argument ${arg}. Supported: --json` };
+    }
+    return { json };
+}
+/**
+ * Entry point invoked from `bin/forge.ts`. Returns the process exit code.
+ *
+ * Exit code: 0 when status === "ready", else 1 — matches pi's own
+ * non-interactive `formatNoModelsAvailableMessage` exit semantics.
+ */
+export async function runDoctor(args, versions) {
+    const parsed = parseDoctorArgs(args);
+    if ("error" in parsed) {
+        process.stderr.write(`${parsed.error}\n`);
+        return 1;
+    }
+    const report = await runDoctorProbe(versions);
+    if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatDoctorReport(report)}\n`);
+    }
+    return report.status === "ready" ? 0 : 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/bin/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/bin/doctor.ts"],"names":[],"mappings":"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"}

package/dist/bin/forge.js

@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
 import { main } from "@earendil-works/pi-coding-agent";
 import forgecli from "../extensions/forgecli/index.js";
 import { isParseError, parseForgeArgv } from "./argv.js";
+import { runDoctor } from "./doctor.js";
 // ---------------------------------------------------------------------------
 // Version information (resolved at startup from package.json files)
 // ---------------------------------------------------------------------------
@@ -78,6 +79,9 @@ Pi options (forwarded verbatim):
 
 Unknown flags are rejected — forge performs strict argv ownership.
 
+Subcommands:
+  doctor [--json]          Preflight check — pi auth, model availability, settings
+
 Slash commands (inside a Forge project):
   /forge:init              Bootstrap a new Forge SDLC project
   /forge:*                 Full Forge command set (when inside a Forge project)
@@ -102,6 +106,15 @@ if (parsed.forgeAction === "help") {
     await main(["--help"], { extensionFactories: [forgecli] });
     process.exit(0);
 }
+if (parsed.forgeAction === "doctor") {
+    const pkg = readForgeCliPkg();
+    const exitCode = await runDoctor(parsed.subcommandArgs ?? [], {
+        forgeCli: pkg.version ?? "unknown",
+        forgePlugin: pkg.forge?.bundledVersion ?? "unknown",
+        pi: await readPiVersion(),
+    });
+    process.exit(exitCode);
+}
 // Apply forge env overrides
 Object.assign(process.env, parsed.env);
 // Default prompt-cache retention to "long" for all Forge sessions.

package/dist/bin/forge.js.map

@@ -1 +1 @@
-{"version":3,"file":"forge.js","sourceRoot":"","sources":["../../src/bin/forge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"forge.js","sourceRoot":"","sources":["../../src/bin/forge.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/fix-bug.js

@@ -22,6 +22,8 @@ import { loadForgePersona, runForgeSubagent } from "./forge-subagent.js";
 import { discoverForgeConfig } from "./forge-root.js";
 import { loadWorkflow } from "./loaders/workflow-loader.js";
 import { getSessionRegistry } from "./session-registry.js";
+import { attachViewportObserver } from "./viewport-events.js";
+import { fmtPhaseSummary } from "./viewport-renderer.js";
 import { validateId, isNonInteractive, formatLocalTime, emitEvent, findPredecessorIndex, runPreflightGate, buildPhaseEvent, drainFrictionFile, judgementFromSummary, } from "./run-task.js";
 // ── Bug phase descriptor table ──────────────────────────────────────────────
 //
@@ -543,11 +545,6 @@ export async function runBugPipeline(opts) {
         }
         // Phase-scoped progress counters
         const phaseStart = Date.now();
-        let turn = 0;
-        let toolCount = 0;
-        let errCount = 0;
-        let lastTool = "";
-        const argsByCallId = new Map();
         // Track tool_execution_end events for bugId capture (Findings #1, #2).
         const toolExecutionEvents = [];
         // Stabilization debug log
@@ -582,49 +579,31 @@ export async function runBugPipeline(opts) {
         }
         writeDebug({ kind: "phase_start", phaseIndex: currentPhaseIndex });
         registry.startPhase(bugId, phase.role, currentPhaseIndex);
-        const argHint = (toolName, args) => {
-            if (!args || typeof args !== "object")
-                return "";
-            const a = args;
-            const fp = (a.file_path ?? a.path);
-            if (typeof fp === "string")
-                return path.basename(fp);
-            if (typeof a.command === "string") {
-                const head = a.command.split(/\s+/).slice(0, 2).join(" ");
-                return head.length > 40 ? `${head.slice(0, 40)}…` : head;
-            }
-            if (typeof a.pattern === "string")
-                return a.pattern.slice(0, 40);
-            if (typeof a.query === "string")
-                return a.query.slice(0, 40);
-            return "";
-        };
-        // Tail-line formatters
-        const formatTime = (ms) => {
-            const d = new Date(ms);
-            const pad = (n) => String(n).padStart(2, "0");
-            return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
-        };
-        const tailPrefix = () => `[${phase.role} ${formatTime(Date.now())}]`;
-        const extractErrorSummary = (result) => {
-            const raw = typeof result === "string"
-                ? result
-                : typeof result === "object" && result !== null
-                    ? JSON.stringify(result)
-                    : String(result);
-            const firstLine = raw.split(/\r?\n/).find((l) => l.trim().length > 0) ?? raw;
-            return firstLine.length > 160 ? `${firstLine.slice(0, 160)}…` : firstLine;
-        };
-        const appendTail = (line, opts) => {
-            registry.appendTail(bugId, phase.role, line, opts);
-        };
-        appendTail(`${tailPrefix()} ─── phase ${phase.role} begin ───`);
         const refreshStatus = () => {
             if (process.env.FORGE_VERBOSE !== "1")
                 return;
             const elapsed = Math.floor((Date.now() - phaseStart) / 1000);
-            const tail = lastTool ? ` · ${lastTool}` : "";
-            ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: ${phase.role} · t${turn} · tools ${toolCount}${errCount ? ` · err ${errCount}` : ""} · ${elapsed}s${tail}`);
+            const tail = observer.state.lastTool ? ` · ${observer.state.lastTool}` : "";
+            ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: ${phase.role} · t${observer.state.turn} · tools ${observer.state.toolCount}${observer.state.errCount ? ` · err ${observer.state.errCount}` : ""} · ${elapsed}s${tail}`);
+        };
+        const observer = attachViewportObserver({
+            registry,
+            sessionId: bugId,
+            phaseRole: phase.role,
+            beginHeader: `─── phase ${phase.role} begin ───`,
+            writeDebug,
+            notify: (msg, level) => ctx.ui.notify(msg, level),
+            setStatusVerbose: process.env.FORGE_VERBOSE === "1" ? (k, v) => ctx.ui.setStatus?.(k, v) : undefined,
+            verboseKeys: { messageKey: `${STATUS_KEY}:message` },
+            afterEach: refreshStatus,
+        });
+        // Wrap the observer's onEvent to also capture tool_execution_end events
+        // for bugId capture downstream (findings #1, #2).
+        const onSubagentEvent = (event) => {
+            if (event?.type === "tool_execution_end") {
+                toolExecutionEvents.push({ toolName: event.toolName, result: event.result });
+            }
+            observer.onEvent(event);
         };
         let result;
         try {
@@ -638,72 +617,7 @@ export async function runBugPipeline(opts) {
                 // namespace so the system-prompt + persona prefix stays warm
                 // across the ~10-minute phases.
                 cacheSessionId: typeof bugRecordBefore?.sprintId === "string" ? `forge:${bugRecordBefore.sprintId}` : `forge:bug:${bugId}`,
-                onEvent: (event) => {
-                    switch (event.type) {
-                        case "turn_start": {
-                            turn++;
-                            lastTool = "";
-                            registry.bumpTurn(bugId);
-                            refreshStatus();
-                            break;
-                        }
-                        case "turn_end": {
-                            // Extract turn preview from assistant message
-                            break;
-                        }
-                        case "tool_execution_start": {
-                            toolCount++;
-                            argsByCallId.set(event.toolCallId, event.args);
-                            const hint = argHint(event.toolName, event.args);
-                            lastTool = `${event.toolName}${hint ? ` ${hint}` : ""}`;
-                            writeDebug({
-                                kind: "tool_start",
-                                toolName: event.toolName,
-                                toolCallId: event.toolCallId,
-                                args: event.args,
-                            });
-                            registry.recordToolStart(bugId, event.toolCallId, event.toolName, event.args);
-                            appendTail(`${tailPrefix()} → ${event.toolName}${hint ? ` ${hint}` : ""}`);
-                            refreshStatus();
-                            break;
-                        }
-                        case "tool_execution_end": {
-                            const startArgs = argsByCallId.get(event.toolCallId);
-                            argsByCallId.delete(event.toolCallId);
-                            // Collect tool_execution_end events for bugId capture (Findings #1, #2).
-                            toolExecutionEvents.push({ toolName: event.toolName, result: event.result });
-                            writeDebug({
-                                kind: "tool_end",
-                                toolName: event.toolName,
-                                toolCallId: event.toolCallId,
-                                isError: event.isError,
-                                args: startArgs,
-                                result: event.result,
-                            });
-                            registry.recordToolEnd(bugId, event.toolCallId, event.toolName, event.isError, event.result);
-                            if (event.isError) {
-                                errCount++;
-                                appendTail(`${tailPrefix()} ⚠ ${event.toolName} failed: ${extractErrorSummary(event.result)}`, { warning: true });
-                            }
-                            else {
-                                appendTail(`${tailPrefix()} ← ${event.toolName} ok`);
-                            }
-                            refreshStatus();
-                            break;
-                        }
-                        case "compaction_start": {
-                            ctx.ui.notify(`◌ ${phase.role}: context compacting (${event.reason})…`, "info");
-                            appendTail(`${tailPrefix()} ◌ compacting (${event.reason})`);
-                            break;
-                        }
-                        case "auto_retry_start": {
-                            const err = event.errorMessage ?? "";
-                            ctx.ui.notify(`↻ ${phase.role}: model retry ${event.attempt}/${event.maxAttempts}${err ? `\n${err}` : ""}`, "warning");
-                            appendTail(`${tailPrefix()} ↻ retry ${event.attempt}/${event.maxAttempts}${err ? `: ${extractErrorSummary(err)}` : ""}`, { warning: true });
-                            break;
-                        }
-                    }
-                },
+                onEvent: onSubagentEvent,
             });
         }
         catch (err) {
@@ -802,7 +716,18 @@ export async function runBugPipeline(opts) {
         }
         {
             const elapsed = Math.floor((Date.now() - phaseStart) / 1000);
+            const { turn, toolCount, errCount, cumUsage } = observer.state;
             ctx.ui.notify(`✓ ${phase.role}: ${turn} turn${turn === 1 ? "" : "s"} · ${toolCount} tool call${toolCount === 1 ? "" : "s"}${errCount ? ` · ${errCount} err` : ""} · ${elapsed}s`, "info");
+            registry.appendTail(bugId, phase.role, fmtPhaseSummary({
+                role: phase.role,
+                turns: turn,
+                tools: toolCount,
+                errors: errCount,
+                wallSeconds: elapsed,
+                usage: cumUsage,
+                model: result.model,
+                provider: result.provider,
+            }));
         }
         // ── Slice-2: orchestrator emits phase event ──────────────────
         // sprintId for bug event emission is the literal "bugs" (routing key),