@kontourai/flow-agents 3.2.0 → 3.4.0

package/context/scripts/hooks/workflow-steering.js

@@ -18,8 +18,9 @@ const fs = require('fs');
 const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 const { resolveActor } = require('./lib/actor-identity');
-const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
+const { flowAgentsArtifactRootsForRead, resolveSharedRepoRoot, warnIfFailingOpenInsideGitTree } = require('./lib/local-artifact-paths');
 const { readCurrentPointer } = require('./lib/current-pointer');
+const { workflowTriggersFor } = require('./lib/kit-catalog');
 
 const STEERING = {
   'tool-planner': [
@@ -71,14 +72,36 @@ const ACTIVE_STATE_STATUSES = new Set([
 ]);
 
 function findRepoRoot(startDir) {
-  let dir = path.resolve(startDir || process.cwd());
+  const resolvedStartDir = path.resolve(startDir || process.cwd());
+  // #357: prefer git's SHARED common-dir root (the primary checkout's repo root, resolved
+  // identically from any linked worktree) before falling back to the plain `.git`/AGENTS.md
+  // ancestor walk below. Without this, a worktree's OWN `.git` FILE (not the shared `.git`
+  // DIRECTORY) satisfies `fs.existsSync(path.join(dir, '.git'))` at the very first directory
+  // checked, so the walk always stopped at the worktree root instead of resolving to the
+  // shared primary checkout — see src/lib/local-artifact-root.ts's resolveSharedRepoRoot doc
+  // comment for the full rationale. Fails open to the walk below (unchanged) when git is
+  // unavailable, `resolvedStartDir` is not inside a git working tree, or the command fails —
+  // this is also exactly today's behavior in the single-checkout case, where
+  // `--git-common-dir` resolves to `.git` under `resolvedStartDir` itself.
+  const sharedRoot = resolveSharedRepoRoot(resolvedStartDir);
+  if (sharedRoot) return sharedRoot;
+  let dir = resolvedStartDir;
   const root = path.parse(dir).root;
   for (let depth = 0; dir && depth < 40; depth++) {
-    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      // #413 iteration-2 Fix 1: resolveSharedRepoRoot failed above even though a `.git` entry
+      // exists right here — git resolution was ATTEMPTED and FAILED (corrupted gitlink, bad
+      // GIT_DIR, git unavailable, etc.), not merely "no git repo at all". Loud, not silent —
+      // see warnIfFailingOpenInsideGitTree's own doc comment for the full rationale. This walk
+      // still returns `dir` (the ancestor-walk fallback is preserved unchanged) after warning.
+      warnIfFailingOpenInsideGitTree(resolvedStartDir, dir);
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
     if (dir === root) break;
     dir = path.dirname(dir);
   }
-  return path.resolve(startDir || process.cwd());
+  return resolvedStartDir;
 }
 
 function walkStateFiles(dir, out = []) {
@@ -159,8 +182,25 @@ function latestWorkflowState(root) {
   return states[0] || null;
 }
 
+// #293 AC7 (injection discipline): strips C0 (0x00-0x1F), DEL (0x7F), and C1 (0x80-0x9F,
+// which includes ANSI-CSI-adjacent bytes) BEFORE whitespace-collapse/truncation — mirroring
+// src/cli/workflow-sidecar.ts's stripControlCharsForDisplay / assignment-provider.ts's
+// sanitizeDisplayField exactly (same charset, same rationale: holder/actor/assignee strings
+// sourced from the shared multi-writer liveness stream or an attacker-postable GitHub comment
+// are untrusted display input). Previously this function only collapsed whitespace, so a raw
+// ESC/BEL byte embedded in a hostile actor string passed through unstripped into every steering
+// notice that calls safeStateText (resumeSteering's LIVENESS WARNING block, supersessionSteering's
+// SUPERSEDED notice) — fixed here, in the one shared helper, rather than in each call site.
 function safeStateText(value, maxLength = 240) {
-  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  // Whitespace-collapse FIRST (so an embedded newline/tab becomes a joining space, preserving
+  // the existing multiline-summary neutralization behavior), THEN strip control/ANSI bytes
+  // (#293 AC7) — reversing this order would strip \n before the collapse ever sees it, losing
+  // the join-space between sentences. Only C0/DEL/C1 bytes THAT SURVIVE the collapse (ESC, BEL,
+  // and other non-whitespace control bytes — real \s already became a plain space above) are
+  // stripped, mirroring src/cli/workflow-sidecar.ts's stripControlCharsForDisplay /
+  // assignment-provider.ts's sanitizeDisplayField charset exactly.
+  const collapsed = String(value || '').replace(/\s+/g, ' ').trim();
+  const text = collapsed.replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
   if (text.length <= maxLength) return text;
   return `${text.slice(0, maxLength - 3)}...`;
 }
@@ -227,6 +267,9 @@ function stateSteering(root) {
     `STATE: ${state.task_slug || path.basename(path.dirname(current.file))} is status:${state.status} phase:${state.phase}.`,
   ];
   if (next.summary) parts.push(`Recorded next_action.summary: "${safeStateText(next.summary)}"`);
+  if (Array.isArray(next.skills) && next.skills.length) parts.push(`Required skills: ${next.skills.map(skill => safeStateText(skill, 80)).join(' -> ')}.`);
+  if (Array.isArray(next.operations) && next.operations.length) parts.push(`Required operations: ${next.operations.map(operation => safeStateText(operation, 80)).join(' -> ')}.`);
+  if (next.command) parts.push(`Run: ${safeStateText(next.command, 240)}`);
   if (next.target_phase) parts.push(`Target phase: ${safeStateText(next.target_phase, 80)}.`);
   if (next.status === 'needs_user' || state.status === 'needs_decision' || state.status === 'not_verified') {
     parts.push('Do not deliver as complete until the user decision or accepted gap is recorded.');
@@ -248,6 +291,52 @@ function contextMapSteering(root) {
   ].join(' ');
 }
 
+/**
+ * Compose the SessionStart advisory line for installed-skill drift (#439). Fires only inside a
+ * kit-bearing checkout (repo has `kits/` AND a built `dist/claude-code/.claude/skills` bundle) —
+ * never triggers a build itself, staying read-only and cheap on every SessionStart. Returns ''
+ * (never throws past this function) in every other case: not kit-bearing, no manifest yet, no
+ * drift found, or any internal error.
+ *
+ * Reuses the SINGLE shared classification choke point, `scripts/hooks/lib/skill-drift.js`'s
+ * `compareSkillDrift()` — this function must never hand-roll its own drift comparison (same
+ * convention the CLI check and the manifest writer follow, see #439 plan).
+ *
+ * @param {string} root  Repository root
+ * @returns {string}
+ */
+function skillDriftSteering(root) {
+  try {
+    if (!fs.existsSync(path.join(root, 'kits'))) return '';
+    if (!fs.existsSync(path.join(root, 'dist', 'claude-code', '.claude', 'skills'))) return '';
+
+    const { loadManifest, compareSkillDrift, resolveClaudeGlobalSkillsDir } = require('./lib/skill-drift');
+
+    const destDir = resolveClaudeGlobalSkillsDir(process.env);
+    // Sibling layout: <destDir>/.flow-agents/skills-manifest.json — mirrors
+    // src/lib/local-artifact-root.ts's durableFlowAgentsRoot(destDir)/skillsManifestPath exactly
+    // (durableFlowAgentsRoot(cwd) resolves to `${cwd}/.flow-agents`, no parent traversal).
+    const manifestPath = path.join(destDir, '.flow-agents', 'skills-manifest.json');
+    const manifest = loadManifest(manifestPath);
+
+    const installedDir = path.join(destDir, 'skills');
+    const kitSourceDir = path.join(root, 'dist', 'claude-code', '.claude', 'skills');
+    const report = compareSkillDrift({ installedDir, kitSourceDir, manifest });
+    if (!report.hasDrift) return '';
+
+    const { kitUpdated, userModified, unbaselined, missingInstall, kitRemoved } = report.summary;
+    // kit_removed (#439 review fix) folds into staleCount alongside the other non-in_sync
+    // states — this advisory line only ever surfaces kit-updated/user-modified counts by name
+    // (see the template string below), so kit_removed does not get its own named count here; it
+    // is still reflected in the total. Full per-state detail is always available via
+    // `flow-agents skill-drift-check`.
+    const staleCount = kitUpdated + userModified + unbaselined + missingInstall + kitRemoved;
+    return `[SKILL DRIFT] ${staleCount} installed Claude Code skill file(s) are stale vs this kit (${kitUpdated} kit-updated, ${userModified} user-modified). Run \`flow-agents init --runtime claude-code --global\` to refresh (user-modified files are reported, not overwritten). See \`flow-agents skill-drift-check\` for details.`;
+  } catch {
+    return '';
+  }
+}
+
 function promptText(input) {
   const candidates = [
     input && input.prompt,
@@ -262,7 +351,7 @@ function promptText(input) {
   return '';
 }
 
-function looksLikeBuilderWork(text) {
+function looksLikeImplementationWork(text) {
   const normalized = safeStateText(text, 2000).toLowerCase();
   if (!normalized) return false;
   const readOnlyIntent = /\b(read[- ]only|review[- ]only|no (source |code |file )?(changes?|edits?|modifications?)|do not (modify|edit|change|write|fix|implement|touch)|don't (modify|edit|change|write|fix|implement|touch)|dont (modify|edit|change|write|fix|implement|touch))\b/.test(normalized);
@@ -281,17 +370,29 @@ function looksLikeBuilderWork(text) {
   return hasWorkVerb || (hasWorkObject && hasRequestLanguage);
 }
 
-function builderWorkflowSteering(input) {
-  if (!looksLikeBuilderWork(promptText(input))) return '';
-  return [
-    'BUILDER WORKFLOW ROUTE: this user prompt looks like coding/build work.',
-    'Builder lifecycle: shape raw ideas -> build selected work -> publish verified branch/PR -> learn correction feedback.',
-    'Before source edits or implementation commands, activate Builder Kit delivery workflow.',
-    'If the user explicitly requested TDD, activate `tdd-workflow`; otherwise activate `deliver` and keep the session on `builder.build`.',
-    'Use `npm run workflow:sidecar -- ensure-session --flow-id builder.build ...` when the repo provides the sidecar writer.',
-    'After local verification, continue to publish/release-readiness and learning-review; do not treat local verification as terminal delivery.',
-    'Do not bypass plan-work -> execute-plan -> review-work -> verify-work for coding tasks; direct implementation is only acceptable when the user explicitly asks for no workflow or explanation-only help.',
-  ].join(' ');
+function looksLikeKnowledgeWork(text) {
+  const normalized = safeStateText(text, 2000).toLowerCase();
+  if (!normalized) return false;
+  return /\b(remember|capture|save|file|bookmark)\s+(this|that|the|my|our)\b/.test(normalized) ||
+    /\bcapture\s+(this\s+)?(decision|learning|lesson|note|context)\b/.test(normalized) ||
+    /\bwhat did we learn about\b/.test(normalized);
+}
+
+function kitWorkflowSteering(input, root) {
+  const prompt = promptText(input);
+  const categories = [];
+  if (looksLikeImplementationWork(prompt)) categories.push('implementation-work-detected');
+  if (looksLikeKnowledgeWork(prompt)) categories.push('knowledge-capture-detected');
+  if (!categories.length) return '';
+  try {
+    return categories
+      .flatMap(category => workflowTriggersFor(root, category))
+      .map(trigger => trigger.steering)
+      .filter(Boolean)
+      .join('\n');
+  } catch {
+    return '';
+  }
 }
 
 /**
@@ -324,6 +425,13 @@ function resumeSteering(root, current) {
     // Full next action (240-char display path, not the 80-char normalization)
     const nextSummary = next.summary ? safeStateText(next.summary, 240) : 'none';
     lines.push(`Next action: ${nextSummary}`);
+    if (Array.isArray(next.skills) && next.skills.length) {
+      lines.push(`Required skills: ${next.skills.map(skill => safeStateText(skill, 80)).join(' -> ')}`);
+    }
+    if (Array.isArray(next.operations) && next.operations.length) {
+      lines.push(`Required operations: ${next.operations.map(operation => safeStateText(operation, 80)).join(' -> ')}`);
+    }
+    if (next.command) lines.push(`Run: ${safeStateText(next.command, 240)}`);
 
     // Plan artifact path
     let planPath = 'not found';
@@ -411,6 +519,51 @@ function resumeSteering(root, current) {
   }
 }
 
+/**
+ * Compose the every-turn SUPERSEDED steering notice (issue #293).
+ *
+ * Unlike resumeSteering()'s RESUME block (SessionStart only), this notice must
+ * surface on EVERY turn (UserPromptSubmit as well as SessionStart) once another
+ * actor holds a fresh liveness claim on the caller's own subject — the
+ * "don't publish, you may be stale" signal the verify-hold gate backstops at
+ * publish time. Reuses the SAME liveness-only join resumeSteering()'s liveness
+ * advisory block already performs (freshHolders(events, slug, selfActor, now)),
+ * not a second computation.
+ *
+ * freshHolders() already excludes selfActor internally (see
+ * scripts/hooks/lib/liveness-read.js), so any holder returned here is by
+ * definition another actor — no additional self-filter is required.
+ *
+ * Fully fail-open: any error anywhere in this function returns '' rather than
+ * throwing, matching every other steering helper in this file.
+ *
+ * @param {string} root     Repository root
+ * @param {{ file: string, payload: object }} current  Latest active state entry (this actor's own)
+ * @returns {string}
+ */
+function supersessionSteering(root, current) {
+  try {
+    const state = current.payload;
+    const workflowDir = path.dirname(current.file);
+    const slug = state.task_slug || path.basename(workflowDir);
+
+    const resolved = resolveActor(process.env);
+    const selfActor = resolved.actor || 'local';
+
+    const events = flowAgentsArtifactRootsForRead(root)
+      .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
+    if (events.length === 0) return '';
+
+    const holders = freshHolders(events, slug, selfActor, Date.now());
+    if (holders.length === 0) return '';
+
+    const holder = holders[0];
+    return `[SUPERSEDED: another agent appears live on this work: actor ${safeStateText(holder.actor)}, last seen ${holder.lastAt}. Your claim on this subject may be stale — do not publish until you re-verify hold (see verify-hold gate) or hand off.]`;
+  } catch {
+    return '';
+  }
+}
+
 function run(rawInput) {
   try {
     const input = JSON.parse(rawInput);
@@ -443,18 +596,35 @@ function run(rawInput) {
     }
 
     if (event === 'UserPromptSubmit') {
-      const builderHint = builderWorkflowSteering(input);
-      if (builderHint) {
-        hints.push(builderHint);
+      const kitHint = kitWorkflowSteering(input, root);
+      if (kitHint) {
+        hints.push(kitHint);
         const contextHint = contextMapSteering(root);
         if (contextHint) hints.push(contextHint);
       }
     }
 
+    // Every-turn supersession notice (#293): fires on UserPromptSubmit (every turn),
+    // not just SessionStart, so a takeover mid-session keeps surfacing the warning.
+    if (event === 'UserPromptSubmit' && current) {
+      const supersessionHint = supersessionSteering(root, current);
+      if (supersessionHint) hints.push(supersessionHint);
+    }
+
     // SessionStart only: append the RESUME block for richer situational awareness
     if (event === 'SessionStart' && current) {
       const resumeBlock = resumeSteering(root, current);
       if (resumeBlock) hints.push(resumeBlock);
+      const supersessionHint = supersessionSteering(root, current);
+      if (supersessionHint) hints.push(supersessionHint);
+    }
+
+    // SessionStart only, unconditional of `current` (#439): the installed-skill drift advisory
+    // fires on every SessionStart inside a kit-bearing checkout, independent of whether an active
+    // workflow session exists — do NOT fold this into the `current`-gated block above.
+    if (event === 'SessionStart') {
+      const driftHint = skillDriftSteering(root);
+      if (driftHint) hints.push(driftHint);
     }
 
     if (shouldAppendWorkflowContext) {
@@ -487,12 +657,14 @@ module.exports = {
   stateSteering,
   critiqueSteering,
   contextMapSteering,
+  skillDriftSteering,
   latestWorkflowState,
   findRepoRoot,
   safeStateText,
   stateNeedsAmbientSteering,
   resumeSteering,
+  supersessionSteering,
   promptText,
-  looksLikeBuilderWork,
-  builderWorkflowSteering,
+  looksLikeImplementationWork,
+  kitWorkflowSteering,
 };

package/context/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/context/scripts/telemetry/install-console-config.sh

@@ -15,6 +15,10 @@ Options:
   --console-token-file PATH
                           File containing the bearer token.
   --console-tenant ID     Tenant identifier for hosted Console routing.
+  --no-economics-relay    Write console_economics_relay=0 to opt out of the
+                          automatic kit-economics relay (default-on once a
+                          Console telemetry sink is configured; see
+                          lib/config.sh).
 EOF
 }
 
@@ -105,6 +109,7 @@ main() {
   local console_token=""
   local console_token_file="${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-${CONSOLE_TELEMETRY_TOKEN_FILE:-}}"
   local console_tenant="${FLOW_AGENTS_CONSOLE_TENANT:-${CONSOLE_TENANT_ID:-}}"
+  local no_economics_relay=0
   telemetry_sinks=()
   if [[ -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" ]]; then
     append_sinks "$FLOW_AGENTS_TELEMETRY_SINKS"
@@ -139,6 +144,10 @@ main() {
         console_tenant="$2"
         shift 2
         ;;
+      --no-economics-relay)
+        no_economics_relay=1
+        shift
+        ;;
       --help|-h)
         usage
         exit 0
@@ -181,7 +190,12 @@ main() {
   done
   [[ "$console_sink_count" -le 1 ]] || die "select at most one Console telemetry sink"
 
-  if [[ -z "$console_url" && -z "$console_endpoint" && -z "$console_token" && -z "$console_tenant" ]]; then
+  if [[ "$console_sink_count" -gt 0 && -z "$console_tenant" ]]; then
+    echo "warning: install-console-config.sh: a Console telemetry sink was selected with no --console-tenant; records will be untenanted" >&2
+  fi
+
+  if [[ -z "$console_url" && -z "$console_endpoint" && -z "$console_token" && -z "$console_tenant" \
+        && "$no_economics_relay" -eq 0 ]]; then
     return 0
   fi
   if [[ -z "$console_url" && -z "$console_endpoint" && ( -n "$console_token" || -n "$console_tenant" ) ]]; then
@@ -199,15 +213,22 @@ main() {
   set_config_key "$conf" "console_telemetry_endpoint_url" "$console_endpoint"
   set_config_key "$conf" "console_telemetry_token" "$console_token"
   set_config_key "$conf" "console_tenant_id" "$console_tenant"
+  if [[ "$no_economics_relay" -eq 1 ]]; then
+    set_config_key "$conf" "console_economics_relay" "0"
+  fi
   if [[ -n "$console_token" ]]; then
     chmod 600 "$conf" 2>/dev/null || true
   fi
 
   local target="${console_endpoint:-$console_url}"
-  if [[ -n "$console_tenant" ]]; then
-    echo "Configured Console telemetry in $conf for $target (tenant: $console_tenant)"
+  if [[ -n "$target" ]]; then
+    if [[ -n "$console_tenant" ]]; then
+      echo "Configured Console telemetry in $conf for $target (tenant: $console_tenant)"
+    else
+      echo "Configured Console telemetry in $conf for $target"
+    fi
   else
-    echo "Configured Console telemetry in $conf for $target"
+    echo "Recorded economics-relay opt-out in $conf"
   fi
 }
 

package/context/scripts/telemetry/lib/config.sh

@@ -2,14 +2,78 @@
 # config.sh — Load telemetry configuration with defaults
 
 TELEMETRY_DIR="${TELEMETRY_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}"
+# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
+# two levels up.
+TELEMETRY_WORKSPACE_ROOT="${TELEMETRY_WORKSPACE_ROOT:-$(cd "${TELEMETRY_DIR}/../.." && pwd)}"
+
+# A workspace/global conf only counts as operator-created (and thus trusted
+# with credentials) if it is mode 600 and owned by the current user.
+# install-console-config.sh always chmod 600s the conf it writes; git can
+# only store 644/755 (never 600), so this gate rejects a conf smuggled in via
+# clone/tarball/PR/supply-chain even if it happens to land at the expected
+# path. Portable across macOS/BSD stat (-f) and GNU/Linux stat (-c).
+telemetry_conf_trusted() {
+  local file="$1" mode owner
+  # Reject symlinks outright: stat below reports the link's own mode/owner
+  # (lstat semantics, no -L), but the config file is later read by following
+  # the link, so a symlink lets `chmod -h 600 <link>` pass this gate while
+  # the read lands on a different, untrusted target. Never trust a link.
+  [[ -L "$file" ]] && return 1
+  [[ -f "$file" ]] || return 1
+  mode=$(stat -f '%Lp' "$file" 2>/dev/null) || mode=$(stat -c '%a' "$file" 2>/dev/null)
+  owner=$(stat -f '%u' "$file" 2>/dev/null) || owner=$(stat -c '%u' "$file" 2>/dev/null)
+  [[ "$mode" == "600" && -n "$owner" && "$owner" == "$(id -u)" ]]
+}
+
+# A candidate that exists on disk but fails telemetry_conf_trusted would
+# otherwise be silently ignored (telemetry stays fail-open with no signal to
+# the operator). Print a one-time, visible warning naming the path and the
+# fix whenever this happens. Never warn when the file is simply absent, and
+# never change which file TELEMETRY_CONFIG_FILE resolves to below -- this is
+# purely additive/observational.
+telemetry_conf_warn_untrusted() {
+  local file="$1"
+  # `-e` catches a regular file; `-L` additionally catches a symlink that
+  # `-e` would miss (a symlink to a directory, or a dangling symlink) --
+  # both of those are rejected by telemetry_conf_trusted's `-L` check above
+  # but must still surface this warning, not silently emit none.
+  [[ -e "$file" || -L "$file" ]] || return 0
+  printf 'warning: config.sh: %s exists but is not trusted (must be mode 600, owned by the current user, and not a symlink); telemetry will ignore it and stay fail-open. Fix with: chmod 600 "%s"\n' "$file" "$file" >&2
+}
+
+# Config file resolution order: (1) explicit TELEMETRY_CONFIG_FILE env always
+# wins; (2) a gitignored per-workspace conf at .kontourai/telemetry-console.conf
+# if present and operator-trusted (project-specific override); (3) a
+# gitignored user-global conf at ~/.flow-agents/telemetry-console.conf if
+# present and operator-trusted, matching the existing ~/.flow-agents
+# install-home convention (see scripts/discover-agents.sh,
+# scripts/context-budget/budget-scan.sh) so one machine-wide install can carry owner
+# credentials without per-workspace wiring; (4) the shipped telemetry.conf
+# default. The shipped scripts/telemetry/telemetry.conf is tracked and ships
+# into every packaged dist bundle, so it must never carry owner credentials.
+# A candidate that exists but fails the trust gate falls through silently
+# (telemetry stays fail-open).
+TELEMETRY_LOCAL_CONFIG_FILE="${TELEMETRY_WORKSPACE_ROOT}/.kontourai/telemetry-console.conf"
+TELEMETRY_GLOBAL_CONFIG_FILE="${HOME:-}/.flow-agents/telemetry-console.conf"
+if [[ -n "${TELEMETRY_CONFIG_FILE:-}" ]]; then
+  :
+elif telemetry_conf_trusted "$TELEMETRY_LOCAL_CONFIG_FILE"; then
+  TELEMETRY_CONFIG_FILE="$TELEMETRY_LOCAL_CONFIG_FILE"
+else
+  telemetry_conf_warn_untrusted "$TELEMETRY_LOCAL_CONFIG_FILE"
+  if [[ -n "${HOME:-}" ]] && telemetry_conf_trusted "$TELEMETRY_GLOBAL_CONFIG_FILE"; then
+    TELEMETRY_CONFIG_FILE="$TELEMETRY_GLOBAL_CONFIG_FILE"
+  else
+    [[ -n "${HOME:-}" ]] && telemetry_conf_warn_untrusted "$TELEMETRY_GLOBAL_CONFIG_FILE"
+    TELEMETRY_CONFIG_FILE="${TELEMETRY_DIR}/telemetry.conf"
+  fi
+fi
 
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
-# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
-# two levels up. Local runtime telemetry defaults under .kontourai/telemetry;
-# explicit TELEMETRY_DATA_DIR still wins.
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.kontourai/telemetry}"
+# Local runtime telemetry defaults under .kontourai/telemetry; explicit
+# TELEMETRY_DATA_DIR still wins.
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-${TELEMETRY_WORKSPACE_ROOT}/.kontourai/telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"
@@ -37,9 +101,16 @@ CONSOLE_TELEMETRY_URL="${CONSOLE_TELEMETRY_URL:-${CONSOLE_URL:-}}"
 CONSOLE_TELEMETRY_ENDPOINT_URL="${CONSOLE_TELEMETRY_ENDPOINT_URL:-}"
 CONSOLE_TELEMETRY_TOKEN="${CONSOLE_TELEMETRY_TOKEN:-${CONSOLE_AUTH_TOKEN:-}}"
 CONSOLE_TENANT_ID="${CONSOLE_TENANT_ID:-}"
+# Economics relay (#469): a caller-pre-set env var is preserved as the starting point; the
+# config-file key (parsed below) can override it, and if no key is present at all the
+# default-on rule below turns it on once a console telemetry sink resolves.
+FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY="${FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY:-}"
+FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL:-}"
+# Set (non-empty) only when the config file carries an explicit console_economics_relay key —
+# distinguishes "operator said 0/1" from "key absent" for the default-on rule below.
+console_economics_relay_raw=""
 # Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
-# otherwise the URL is derived from the console below so all runtimes read one
-# live pricing source. Falls back to the bundled pricing.json offline.
+# otherwise lib/pricing.sh uses the bundled pricing.json offline.
 TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
 TELEMETRY_PRICING_URL="${TELEMETRY_PRICING_URL:-${FLOW_AGENTS_PRICING_URL:-}}"
 
@@ -82,6 +153,17 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
         console_telemetry_token) CONSOLE_TELEMETRY_TOKEN="$value" ;;
         console_tenant_id) CONSOLE_TENANT_ID="$value" ;;
         console_telemetry_redact) CONSOLE_TELEMETRY_REDACT="$value" ;;
+        console_economics_relay)
+          case "$(echo "$value" | tr '[:upper:]' '[:lower:]')" in
+            1|true|yes|on) console_economics_relay_raw="1" ;;
+            0|false|no|off) console_economics_relay_raw="0" ;;
+            *)
+              printf 'warning: config.sh: unrecognized console_economics_relay value %q; treating as off\n' "$value" >&2
+              console_economics_relay_raw="$value"
+              ;;
+          esac
+          ;;
+        console_economics_endpoint_url) FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="$value" ;;
         console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
@@ -92,12 +174,20 @@ fi
 
 CONSOLE_TELEMETRY_REDACT="${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT}}"
 
-# Derive the live pricing source from the console when not set explicitly, the
-# same way the transport derives /api/telemetry/records. One live source for
-# bash/Python/TS runtimes; lib/pricing.sh caches it and falls back to bundled.
-if [[ -z "${TELEMETRY_PRICING_URL:-}" && -n "${CONSOLE_TELEMETRY_URL:-}" ]]; then
-  TELEMETRY_PRICING_URL="${CONSOLE_TELEMETRY_URL%/}/api/telemetry/pricing"
+# Economics relay default-on rule (#469, opt-out not silent-off): an explicit
+# console_economics_relay config key always wins. Otherwise, once a console telemetry sink is
+# resolved (console_telemetry_url/console_telemetry_endpoint_url non-empty) the relay defaults ON —
+# unless a caller already pre-set FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY in the environment, which is
+# left untouched. economics-record.sh's own opt-in gate (unchanged) reads this exact variable.
+if [[ -n "$console_economics_relay_raw" ]]; then
+  FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY="$console_economics_relay_raw"
+elif [[ -z "$FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY" \
+      && ( -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ) ]]; then
+  FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
 fi
 
+# Pricing URL is explicit-only (env or config). Do not derive the console
+# pricing endpoint by default; the bundled registry is the reliable offline floor.
+
 # Ensure directories exist
 mkdir -p "$TELEMETRY_DATA_DIR" "$TELEMETRY_SESSION_DIR" 2>/dev/null

package/context/scripts/telemetry/lib/pricing.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# pricing.sh — single-source pricing registry loader.
+#
+# Resolves the versioned pricing registry (pricing.json) from, in priority:
+#   1. explicit local file   TELEMETRY_PRICING_FILE / FLOW_AGENTS_PRICING_FILE
+#   2. remote URL (cached)   TELEMETRY_PRICING_URL  / FLOW_AGENTS_PRICING_URL
+#   3. bundled snapshot      <telemetry>/pricing.json
+# This is the one source every runtime + the console read from — local for
+# air-gapped use, remote for a single live registry shared across machines.
+
+PRICING_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+pricing_registry_valid_json() {
+  command -v jq >/dev/null 2>&1 || return 1
+  jq -e '.current_version and .versions' >/dev/null 2>&1
+}
+
+# Echo the raw registry JSON. Returns non-zero if nothing resolvable.
+pricing_registry() {
+  local f="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
+  if [[ -n "$f" && -f "$f" ]]; then cat "$f"; return 0; fi
+
+  local url="${TELEMETRY_PRICING_URL:-${FLOW_AGENTS_PRICING_URL:-}}"
+  if [[ -n "$url" ]] && command -v curl >/dev/null 2>&1; then
+    local cache="${TMPDIR:-/tmp}/flow-agents-pricing-cache.json"
+    local ttl="${TELEMETRY_PRICING_TTL_SEC:-3600}"
+    if [[ -f "$cache" ]]; then
+      local mtime now age
+      mtime=$(stat -c %Y "$cache" 2>/dev/null || stat -f %m "$cache" 2>/dev/null || echo 0)
+      [[ "$mtime" =~ ^[0-9]+$ ]] || mtime=0
+      now=$(date +%s)
+      age=$(( now - mtime ))
+      if [[ "$age" -lt "$ttl" ]] && pricing_registry_valid_json < "$cache"; then cat "$cache"; return 0; fi
+    fi
+    if curl -fsS --max-time 5 "$url" -o "${cache}.tmp" 2>/dev/null && [[ -s "${cache}.tmp" ]]; then
+      if pricing_registry_valid_json < "${cache}.tmp"; then
+        mv "${cache}.tmp" "$cache"
+        cat "$cache"
+        return 0
+      fi
+    fi
+    rm -f "${cache}.tmp" 2>/dev/null
+    [[ -f "$cache" ]] && pricing_registry_valid_json < "$cache" && { cat "$cache"; return 0; }
+  fi
+
+  local bundled
+  bundled="$(cd "${PRICING_LIB_DIR}/.." && pwd)/pricing.json"
+  [[ -f "$bundled" ]] && { cat "$bundled"; return 0; }
+  return 1
+}

package/context/scripts/telemetry/lib/session.sh

@@ -60,4 +60,7 @@ session_end() {
 
 session_cleanup() {
   find "${TELEMETRY_SESSION_DIR}" -name "*.session" -mtime +1 -delete 2>/dev/null || true
+  # Bound the per-cwd project-label cache (see console_project_label) so a project rename
+  # (package.json name / git remote) self-heals within the same window instead of caching forever.
+  find "${TELEMETRY_SESSION_DIR}" -name "project-label.*" -mtime +1 -delete 2>/dev/null || true
 }