forgedock 1.1.7 → 1.1.9

package/bin/registry.mjs

@@ -11,6 +11,8 @@
  *   setOptOut(dir, optedOut)   → Promise<void>  (adds/removes dir from opt-out set)
  *   nudgeSeen(dir)             → boolean  (true if nudge was already shown for dir)
  *   markNudgeSeen(dir)         → Promise<void>  (records that nudge was shown for dir)
+ *   getPersistedHomeState()    → { path, version, updatedAt } | null  (reads persistedHome)
+ *   setPersistedHomeState(s)   → Promise<void>  (writes persistedHome; see #1943)
  *
  * Registry file: ~/.claude/forgedock/registry.json
  * Registry schema:
@@ -21,7 +23,12 @@
  *     },
  *     "nudgeSeen": {
  *       "/absolute/path/to/dir": { "at": "<ISO-8601 timestamp>" }
- *     }
+ *     },
+ *     "persistedHome": {
+ *       "path": "/absolute/path/to/~/.forge",
+ *       "version": "1.2.3",
+ *       "updatedAt": "<ISO-8601 timestamp>"
+ *     } | null
  *   }
  *
  * State model:
@@ -33,6 +40,12 @@
  *     registry always fails open (never blocks a Claude Code session).
  *   - A nudge is shown at most once per unmanaged directory; `nudgeSeen` tracks
  *     which directories have already received the nudge.
+ *   - `persistedHome` records the last known state of the persisted-toolset
+ *     copy (bin/journey.mjs: persistHome(), issue #1943) written under
+ *     `~/.forge/`. `null` means persistHome() has never run (or was skipped —
+ *     e.g. a git-clone install) for this user. This is metadata ABOUT that
+ *     copy — the copy itself is not stored here; only registry.mjs's own
+ *     `~/.claude/forgedock/registry.json` lives in this file.
  *
  * Contract guarantees:
  *   - Safe: every try/catch degrades gracefully; resolveState never throws
@@ -77,10 +90,10 @@ const REGISTRY_PATH = join(REGISTRY_DIR, "registry.json");
  * Empty registry structure — returned whenever the file is missing or corrupt.
  * Using a factory function avoids shared mutable state across calls.
  *
- * @returns {{ version: number, optedOut: Record<string, { at: string }>, nudgeSeen: Record<string, { at: string }> }}
+ * @returns {{ version: number, optedOut: Record<string, { at: string }>, nudgeSeen: Record<string, { at: string }>, persistedHome: null }}
  */
 function emptyRegistry() {
-  return { version: 1, optedOut: {}, nudgeSeen: {} };
+  return { version: 1, optedOut: {}, nudgeSeen: {}, persistedHome: null };
 }
 
 // ---------------------------------------------------------------------------
@@ -162,6 +175,11 @@ function readRegistry() {
       if (!parsed.nudgeSeen || typeof parsed.nudgeSeen !== "object") {
         parsed.nudgeSeen = {};
       }
+      // Ensure persistedHome is present (absent in registry files written
+      // before #1943 added persisted-home tracking).
+      if (parsed.persistedHome === undefined) {
+        parsed.persistedHome = null;
+      }
       return parsed;
     }
     // Schema mismatch — treat as empty (fail open)
@@ -377,6 +395,76 @@ export async function clearNudgeSeen(dir) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Persisted-home state tracking (issue #1943)
+// ---------------------------------------------------------------------------
+// bin/journey.mjs's persistHome() copies ForgeDock's own toolset (bin/,
+// commands/, scripts/, templates/) into a stable `~/.forge/` home so
+// ~/.claude/commands/ symlinks and the SessionStart hook's script path
+// survive npm/npx cache eviction. These two functions are the single place
+// doctor()/update() read and write what persistHome() last did, so both
+// commands agree on "where does the persisted copy live and what version is
+// it" instead of each re-deriving it independently (forge#1589's split-brain
+// precedent — install/doctor/status previously disagreed about where
+// ForgeDock lived, and this issue must not reintroduce that).
+
+/**
+ * Read the last recorded persisted-home state from the registry.
+ *
+ * NOT pure: reads `~/.claude/forgedock/registry.json` from disk on every
+ * call. Fail-open — a missing/corrupt registry file, or a registry written
+ * before #1943, both resolve to `null` (equivalent to "persistHome() has
+ * never recorded state for this user") rather than throwing.
+ *
+ * @returns {{ path: string, version: string, updatedAt: string } | null}
+ */
+export function getPersistedHomeState() {
+  try {
+    const registry = readRegistry();
+    return registry.persistedHome ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record the current persisted-home state in the registry.
+ *
+ * NOT pure: performs a disk write (via the atomic `.tmp` + `renameSync`
+ * pattern in `_doWriteRegistryWith`) and, when the caller omits `updatedAt`,
+ * calls `new Date()` to stamp one — this function has real side effects, it
+ * does not merely compute a value (see forge#462: a prior JSDoc/behavior
+ * mismatch in this file claimed a writer was a "pure mutation function" when
+ * it in fact touched the clock and the filesystem — documenting that
+ * honestly here rather than repeating it).
+ *
+ * Best-effort: write failures are swallowed by writeRegistry()'s existing
+ * fail-open contract; a failed write leaves the previous persistedHome value
+ * (or null) in place rather than throwing.
+ *
+ * @param {{ path: string, version: string, updatedAt?: string }} state
+ * @returns {Promise<void>}
+ */
+export async function setPersistedHomeState({ path, version, updatedAt } = {}) {
+  // Normalize the same way normalizeDir() does elsewhere in this file
+  // (lowercase Windows drive letter) so a later lookup never mismatches on
+  // drive-letter casing alone (forge#412 precedent). Falls back to the raw
+  // path if it doesn't exist yet or can't be resolved — never throws.
+  let normalizedPath = path;
+  try {
+    if (path) normalizedPath = normalizeDir(path);
+  } catch {
+    normalizedPath = path;
+  }
+  await writeRegistry((registry) => {
+    registry.persistedHome = {
+      path: normalizedPath,
+      version: version || "",
+      updatedAt: updatedAt || new Date().toISOString(),
+    };
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Claude Code version detection and breakpoints resolution (issue #1252)
 // ---------------------------------------------------------------------------

package/bin/runner.mjs

@@ -23,6 +23,7 @@
  *   getToolHandlers(cwd)                    → Record<string, fn>
  *   renderDryRun(ctx)                       → string
  *   renderSummaryCard(ctx)                  → string
+ *   resolveConfiguredDefaultModel(cwd)      → string|null   (forge.yaml agents.default_model, resolved)
  *   runCommand(opts)                        → Promise<{status, ...}>
  *
  * Design notes:
@@ -45,6 +46,7 @@ import {
 } from "fs";
 import { join, dirname, basename, relative, isAbsolute } from "path";
 import { execSync, spawnSync } from "child_process";
+import { parseForgeYaml, resolveModelAlias } from "./forge-utils.mjs";
 
 const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
@@ -74,6 +76,36 @@ export function truncateToolResult(content) {
   return str.slice(0, MAX_TOOL_RESULT_CHARS) + TRUNCATION_MARKER;
 }
 
+/**
+ * Resolve the project-configured default model from forge.yaml's
+ * `agents.default_model` field, if present.
+ *
+ * Reads `{cwd}/forge.yaml` (a fixed, non-agent-controlled filename — not the
+ * LLM-facing `resolveConfinedPath` path-confinement helper used for tool-call
+ * paths below), parses it with the shared `parseForgeYaml`, and resolves the
+ * `agents.default_model` alias (`sonnet`/`opus`/`haiku`, or a pass-through
+ * full model ID) via `resolveModelAlias`.
+ *
+ * Fail-soft: returns `null` on any failure (forge.yaml missing, unreadable,
+ * malformed, or the field absent) so the headless runner keeps working with
+ * zero configuration — this is a fallback tier, not a requirement.
+ *
+ * @param {string} cwd - Working directory to look for forge.yaml in.
+ * @returns {string|null}
+ */
+export function resolveConfiguredDefaultModel(cwd) {
+  try {
+    const forgeYamlPath = join(cwd, "forge.yaml");
+    if (!existsSync(forgeYamlPath)) return null;
+    const raw = readFileSync(forgeYamlPath, "utf-8");
+    const parsed = parseForgeYaml(raw);
+    const configured = parsed?.agents?.default_model;
+    return resolveModelAlias(configured);
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Command spec resolution
 // ---------------------------------------------------------------------------
@@ -734,7 +766,9 @@ export function renderSummaryCard(ctx) {
  * @param {string[]} [opts.args]             - Command arguments.
  * @param {string} [opts.cwd]                - Working directory (default cwd).
  * @param {string} [opts.apiKey]             - Anthropic API key (default env).
- * @param {string} [opts.model]              - Model id.
+ * @param {string} [opts.model]              - Model id. Resolution order when
+ *   omitted: $FORGEDOCK_MODEL env > forge.yaml `agents.default_model` (in
+ *   `cwd`) > hardcoded DEFAULT_MODEL.
  * @param {number} [opts.maxIterations]      - Tool-loop bound.
  * @param {boolean} [opts.dryRun]            - Preview without an API call.
  * @param {{log: Function, error?: Function}} [opts.logger] - Output sink.
@@ -747,7 +781,9 @@ export async function runCommand(opts = {}) {
     args = [],
     cwd = process.cwd(),
     apiKey = process.env.ANTHROPIC_API_KEY,
-    model = process.env.FORGEDOCK_MODEL || DEFAULT_MODEL,
+    model = process.env.FORGEDOCK_MODEL ||
+      resolveConfiguredDefaultModel(cwd) ||
+      DEFAULT_MODEL,
     maxIterations = DEFAULT_MAX_ITERATIONS,
     dryRun = false,
     logger = console,

package/bin/tui.mjs

@@ -631,7 +631,9 @@ const STEP_STATUS = {
  * their own ASCII symbols.
  */
 export function stepHeader(current, total, label, status = "active") {
-  const icon = STEP_STATUS[status] || STEP_STATUS.active;
+  const icon = Object.hasOwn(STEP_STATUS, status)
+    ? STEP_STATUS[status]
+    : STEP_STATUS.active;
   const counter = dim(`Step ${current} of ${total}`);
   const dash = dim(" — ");
   const name =
@@ -1589,6 +1591,44 @@ function gradientText(text, start, end) {
   return result + RST;
 }
 
+/**
+ * Default tagline — used when no context is given, or the given context has
+ * no mapped entry in LOGO_TAGLINES.
+ */
+const DEFAULT_TAGLINE = "GitHub as a knowledge graph for AI agents";
+
+/**
+ * Context-specific taglines shown under the logo. Keyed by the invoking
+ * command/context name. Any context not listed here falls back to
+ * DEFAULT_TAGLINE — this map is additive, never a requirement to cover every
+ * caller.
+ */
+const LOGO_TAGLINES = {
+  install: "lighting the forge",
+  update: "tempering the blade",
+  uninstall: "banking the coals",
+  doctor: "inspecting the anvil",
+  status: "reading the heat",
+};
+
+/**
+ * Look up the tagline for a given invocation context. Exposed so callers
+ * outside renderLogo() (e.g. plain-text command headers that don't render
+ * the full logo) can still surface the same context-specific tagline text.
+ *
+ * Uses an own-property guard rather than a plain `LOGO_TAGLINES[context]`
+ * lookup: `context` is a raw, unsanitized command-name string, and a plain
+ * bracket lookup on an object literal resolves inherited Object.prototype
+ * members (e.g. context === "constructor") instead of falling through to
+ * the default tagline. See forge#1955.
+ *
+ * @param {string} [context]
+ * @returns {string}
+ */
+export function getLogoTagline(context = "") {
+  return Object.hasOwn(LOGO_TAGLINES, context) ? LOGO_TAGLINES[context] : DEFAULT_TAGLINE;
+}
+
 /**
  * Render the ForgeDock logo for display in the terminal.
  *
@@ -1598,10 +1638,16 @@ function gradientText(text, start, end) {
  *
  * @param {object} [opts]
  * @param {string} [opts.version]  - Package version string (e.g. "1.0.14")
+ * @param {string} [opts.context]  - Invocation context (e.g. "install",
+ *   "update", "uninstall", "doctor", "status"). Selects the tagline shown
+ *   under the logo. Unmapped or omitted contexts fall back to the default
+ *   tagline.
  * @returns {string} Rendered logo string (may contain ANSI sequences)
  */
-export function renderLogo({ version = "" } = {}) {
-  const tagline = "GitHub as a knowledge graph for AI agents";
+export function renderLogo({ version = "", context = "" } = {}) {
+  const tagline = Object.hasOwn(LOGO_TAGLINES, context)
+    ? LOGO_TAGLINES[context]
+    : DEFAULT_TAGLINE;
   const versionStr = version ? `ForgeDock · v${version}` : "ForgeDock";
 
   if (!USE_TRUECOLOR) {

package/commands/adopt.md

@@ -12,7 +12,7 @@ You onboard an existing repo into the ForgeDock pipeline. Unlike `/forgedock-ini
 
 Run `/adopt` once after `npx forgedock init` + `/forgedock-init` to make a legacy backlog pipeline-ready without touching the issues themselves.
 
-**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 <!-- FORGE:SPEC_LOADED — adopt.md loaded and active. Agent is bound by this spec. -->

package/commands/analytics.md

@@ -13,7 +13,7 @@ You are the analytics orchestrator. Pull data from ALL available analytics platf
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
-**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model explicitly in every `Agent` tool call. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model explicitly in every `Agent` tool call. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 <!-- FORGE:SPEC_LOADED — analytics.md loaded and active. Agent is bound by this spec. -->
 
@@ -163,7 +163,7 @@ Launch ALL 7 data collection agents simultaneously using `run_in_background=true
 
 ### Agent 1: GSC Data Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Google Search Console data for `{DOMAIN}`. Use the MCP GSC tools directly.
 
@@ -183,7 +183,7 @@ All queries use `siteUrl: "{SITE_URL}"`.
 
 ### Agent 2: Clarity Data Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Microsoft Clarity behavior analytics. Use `mcp__clarity__query-analytics-dashboard` and `mcp__clarity__list-session-recordings` tools.
 
@@ -211,7 +211,7 @@ Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
 ### Agent 3: Umami Data Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Umami analytics via REST API.
 
@@ -238,7 +238,7 @@ python3 -c "import yaml; c=yaml.safe_load(open('{CREDENTIALS_FILE}')); print(c['
 
 ### Agent 4: Cloudflare Data Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Cloudflare traffic/performance data via GraphQL API.
 
@@ -261,7 +261,7 @@ CF_ZONE=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FILE}
 
 ### Agent 5: Bing Webmaster Data Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Bing Webmaster Tools data for `{DOMAIN}` via REST API. Bing powers ChatGPT search, so Bing indexing/ranking data = AI discoverability signal.
 
@@ -288,7 +288,7 @@ BING_BASE=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FIL
 
 ### Agent 6: Stripe Revenue Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Stripe billing and revenue data using Stripe MCP tools. First load them via `ToolSearch query: "+stripe"`, then call the relevant tools.
 
@@ -309,7 +309,7 @@ Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
 ### Agent 7: GA4 Data Collector
 
-Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
+Launch as a background Agent (subagent_type: general-purpose, model: {SUBAGENT_MODEL}):
 
 **Mission**: Collect Google Analytics 4 data via the GA4 Data API (v1beta) using a service account.
 

package/commands/audit.md

@@ -14,7 +14,7 @@ You are Forge's post-mortem auditor. When something reaches production that shou
 
 **This command ALWAYS files issues to `{FORGE_REPO}`.** The target project is read-only — you only read its GitHub artifacts as evidence.
 
-**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 **NEVER use plan mode (EnterPlanMode).**