W1: guarded migration of every executable state-root site; uninstall deletes only ~/.gstack

Bins, careful/freeze hooks, setup, upgrade migrations, browse/src, design,
ios-qa daemon, lib and scripts resolve the state root through
bin/gstack-state-root.sh (bash) or lib/state-root.ts (TS). Bins source the
twin and stop with a reinstall message when it is missing; hooks source it
and never spawn gstack-paths. browse/src/config.ts and lib/cso/state.ts
delegate to resolveStateRoot. Analytics writers and readers move together
so the usage log stays one file. gstack-uninstall deletes state only at
~/.gstack, refuses (exit 2) when it resolves to /, $HOME or an ancestor,
the checkout or the git root, and leaves any other resolved root in place
with the removal command. Fixtures that copy single bins now copy the twin.

scripts/analytics.ts

@@ -13,7 +13,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
+import { resolveStateRoot } from '../lib/state-root';
 
 export interface AnalyticsEvent {
   skill: string;
@@ -23,7 +23,7 @@ export interface AnalyticsEvent {
   pattern?: string;
 }
 
-const ANALYTICS_FILE = path.join(os.homedir(), '.gstack', 'analytics', 'skill-usage.jsonl');
+const ANALYTICS_FILE = path.join(resolveStateRoot(), 'analytics', 'skill-usage.jsonl');
 
 /**
  * Parse JSONL content into AnalyticsEvent[], skipping malformed lines.

scripts/declared-annotation.ts

@@ -22,9 +22,9 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 
 import { SIGNAL_MAP, type Dimension, ALL_DIMENSIONS } from './psychographic-signals';
+import { resolveStateRoot } from '../lib/state-root';
 
 const STRONG_HIGH = 0.7;
 const STRONG_LOW = 0.3;
@@ -61,11 +61,7 @@ interface DeveloperProfile {
 }
 
 function stateRoot(): string {
-  return (
-    process.env.GSTACK_STATE_ROOT ||
-    process.env.GSTACK_HOME ||
-    path.join(os.homedir(), '.gstack')
-  );
+  return resolveStateRoot();
 }
 
 function readProfile(): DeveloperProfile | null {

scripts/gen-skill-docs.ts

@@ -27,6 +27,7 @@ import type { HostConfig } from './host-config';
 
 const ROOT = path.resolve(import.meta.dir, '..');
 import { ALL_MODEL_NAMES, resolveModel, type Model } from './models';
+import { resolveStateRoot } from '../lib/state-root';
 
 type HostArg = Host | 'all';
 
@@ -75,7 +76,7 @@ export interface GenerationResult {
 /** Canonical generation never reads local detection state unless opted in. */
 function loadGbrainOverride(respectDetection: boolean): boolean {
   if (!respectDetection) return false;
-  const stateDir = process.env.GSTACK_HOME || path.join(process.env.HOME || '', '.gstack');
+  const stateDir = resolveStateRoot();
   try {
     const json = JSON.parse(fs.readFileSync(path.join(stateDir, 'gbrain-detection.json'), 'utf-8'));
     // Slow, remote, and locked engines are still usable (#1964/#2051/#2456).
@@ -1087,7 +1088,7 @@ export async function main(args = process.argv.slice(2)): Promise<number> {
     }
     if (!settings.dryRun) {
       try {
-        const config = fs.readFileSync(path.join(process.env.HOME || '', '.gstack', 'config.yaml'), 'utf-8');
+        const config = fs.readFileSync(path.join(resolveStateRoot(), 'config.yaml'), 'utf-8');
         if (/^skill_prefix:\s*true/m.test(config)) {
           console.log('\nNote: skill_prefix is true. Run gstack-relink to re-apply name: patches (it patches both the install and any active gbrain render).');
         }