fix(observe,skills): gitignore the local state the CLI writes; make the Codex hook portable

src/commands/observe.ts

@@ -1,16 +1,36 @@
 // `insta observe` — the local credential-audit hook. install wires a PostToolUse hook into the
 // agent harness; report renders the local audit; sync uploads findings into the project timeline
 // (idempotent via a stable dedup key, matching the platform's audit-event ingest).
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { installObserve, uninstallObserve } from '../observe/install.js'
+import { untrackHint } from '../gitignore.js'
+import { findProjectRoot } from '../config.js'
 import { renderReport } from '../observe/report.js'
 import { ApiClient, requireProject } from '../api.js'
 import { info, printJson } from '../util.js'
 
+// Where the audit lives: the hook records at the directory it is materialized in
+// (<root>/.insta/observe/hook.js — see projectRootFor), so report/sync must anchor on the same
+// thing. The link file is the usual root, but a standalone `insta observe install` in an
+// unlinked directory has no project.json — climb for the hook itself then, so both halves agree
+// from any subdirectory. Falls back to cwd when neither exists (→ "audit log is empty").
+export async function auditRoot(cwd = process.cwd()): Promise<string> {
+  const linked = await findProjectRoot(cwd)
+  if (linked) return linked
+  let dir = resolve(cwd)
+  for (;;) {
+    if (existsSync(join(dir, '.insta', 'observe', 'hook.js'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return cwd
+    dir = parent
+  }
+}
+
 async function readAudit(): Promise<Array<Record<string, unknown>>> {
   try {
-    const txt = await readFile(join(process.cwd(), '.insta', 'audit.jsonl'), 'utf8')
+    const txt = await readFile(join(await auditRoot(), '.insta', 'audit.jsonl'), 'utf8')
     return txt.split('\n').filter(Boolean).map((l) => JSON.parse(l))
   } catch {
     return []
@@ -28,6 +48,9 @@ function* chunk<T>(a: T[], n: number): Generator<T[]> {
 export async function observeInstall(): Promise<void> {
   const res = installObserve({ cwd: process.cwd() })
   info(`installed observe hook (claude: ${res.claude}, codex: ${res.codex}) → ./.insta/observe`)
+  if (res.ignored.length) info(`  .gitignore += ${res.ignored.join(', ')}`)
+  const hint = untrackHint(res.tracked)
+  if (hint) info(hint)
   info('it scans agent tool-use for credential exposure; findings append to ./.insta/audit.jsonl')
   info('run `insta observe report` to review, `insta observe sync` to upload to the project timeline')
 }

src/commands/project.ts

@@ -3,6 +3,7 @@ import { ApiClient, requireProject } from '../api.js'
 import { writeProject } from '../config.js'
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js'
 import { installObserve } from '../observe/install.js'
+import { untrackHint } from '../gitignore.js'
 import { installSkills } from '../ensure-skills.js'
 
 // Generic directory names that make a useless project name ("projects", "~", "tmp", …). When the
@@ -19,10 +20,11 @@ const GENERIC_DIRS = new Set([
 function tryInstallObserve(quiet = false): void {
   try {
     const r = installObserve({ cwd: process.cwd() })
-    if (r.claude || r.codex) {
-      const line = '  installed observe hook (credential audit) → ./.insta/observe'
-      quiet ? process.stderr.write(line + '\n') : info(line)
-    }
+    const say = (line: string) => (quiet ? process.stderr.write(line + '\n') : info(line))
+    if (r.claude || r.codex) say('  installed observe hook (credential audit) → ./.insta/observe')
+    if (r.ignored.length) say(`  .gitignore += ${r.ignored.join(', ')}`)
+    const hint = untrackHint(r.tracked)
+    if (hint) say(hint)
   } catch { /* assets missing (dev/unbuilt) — skip silently */ }
 }
 

src/ensure-skills.ts

@@ -6,16 +6,21 @@
 // repo moved) prints a manual fallback and never blocks or fails the host command — same contract
 // as the observe-hook install.
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { resolveEnv } from './config.js'
 import { resolveSpawnable } from './commands/setup.js'
 import { DEFAULT_ENV, ENVS } from './env.js'
+import { alreadyTracked, ensureGitignore, untrackHint } from './gitignore.js'
+
+export { ensureGitignore } from './gitignore.js'
 
 // Where `npx skills add` drops skills for the agents we pin below: Claude Code → .claude/skills/,
-// Codex → .agents/skills/ (.github/skills/ is the third well-known dir). These are regenerable
-// agent context, not the developer's source — keep them out of git.
-const SKILL_DIRS = ['.claude/skills/', '.agents/skills/', '.github/skills/']
+// Codex → .agents/skills/ (.github/skills/ is the third well-known dir), plus the skills-lock.json
+// it writes at the project root. All regenerable agent context, not the developer's source — keep
+// them out of git. The lock goes too: its payload is already ignored, it pins only a content hash
+// (not the prod/staging source this CLI resolves per environment), and `insta project link` is
+// the restore path — so a committed lock would be a lockfile for nothing.
+const SKILL_DIRS = ['.claude/skills/', '.agents/skills/', '.github/skills/', 'skills-lock.json']
+const GITIGNORE_COMMENT = '# InstaCloud: agent skills installed by `npx skills add` (regenerable, not source)'
 
 export type Runner = (cmd: string, args: string[], inherit?: boolean) => Promise<{ ok: boolean }>
 
@@ -87,31 +92,24 @@ export async function installSkills(deps: Deps): Promise<void> {
       targets = skillTargets(skills)
     } catch { /* keep production defaults */ }
     print('  installing related agent skills (insta, tigris, better-auth) …')
+    let installed = 0
     for (const s of targets) {
       // Don't stream: the `skills` tool's clack UI (clone spinner, banners) is noise. Run it
       // silent (stdio 'ignore') and let the per-skill ✓/failed line below be the clean output —
       // it appears as each skill finishes, so there's still live progress. (Also avoids the
       // child inheriting a piped stdin.)
       const r = await run('npx', s.args)
+      if (r.ok) installed++
       print(r.ok ? `  ${s.label} ✓` : `  ${s.label} failed — add manually: npx ${s.args.join(' ')}`)
     }
-    const added = ensureGitignore(deps.cwd, SKILL_DIRS)
+    // Only when something was actually written: an offline run that failed every add has no
+    // skill dirs or lock to ignore, and a `.gitignore +=` line there would claim otherwise.
+    if (installed === 0) return
+    const added = ensureGitignore(deps.cwd, SKILL_DIRS, GITIGNORE_COMMENT)
     if (added.length) print(`  .gitignore += ${added.join(', ')}`)
+    const hint = untrackHint(alreadyTracked(deps.cwd, SKILL_DIRS))
+    if (hint) print(hint)
   } catch {
     /* best-effort convenience — never block the host command */
   }
 }
-
-// Append any missing entries to the project's ./.gitignore (creating it if absent). Idempotent:
-// entries already present are left alone. Returns the entries it added.
-export function ensureGitignore(cwd: string, entries: string[]): string[] {
-  const p = join(cwd, '.gitignore')
-  const existing = existsSync(p) ? readFileSync(p, 'utf8') : ''
-  const have = new Set(existing.split('\n').map((l) => l.trim()))
-  const missing = entries.filter((e) => !have.has(e))
-  if (missing.length === 0) return []
-  const prefix = existing && !existing.endsWith('\n') ? '\n' : ''
-  const comment = '# InstaCloud: agent skills installed by `npx skills add` (regenerable, not source)'
-  writeFileSync(p, existing + `${prefix}\n${comment}\n${missing.join('\n')}\n`)
-  return missing
-}

src/gitignore.ts

@@ -0,0 +1,43 @@
+// Shared `.gitignore` maintenance for files the CLI writes into a project that are not the
+// developer's source (installed skills, observe-hook state). The rule: whatever writes a
+// regenerable or machine-local file adds its ignore entry in the same step, so `git status` never
+// surfaces it as a surprise — the same convention as `insta secrets` for .env.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// Append any missing entries to the project's ./.gitignore (creating it if absent). Idempotent:
+// entries already present (exact line match) are left alone; a block gets one `comment` header
+// the first time it contributes. Returns the entries it added.
+export function ensureGitignore(cwd: string, entries: string[], comment?: string): string[] {
+  const p = join(cwd, '.gitignore')
+  const existing = existsSync(p) ? readFileSync(p, 'utf8') : ''
+  const have = new Set(existing.split('\n').map((l) => l.trim()))
+  const missing = entries.filter((e) => !have.has(e))
+  if (missing.length === 0) return []
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : ''
+  const header = comment && !have.has(comment) ? `${comment}\n` : ''
+  writeFileSync(p, existing + `${prefix}\n${header}${missing.join('\n')}\n`)
+  return missing
+}
+
+// An ignore entry does nothing for a path git already tracks — and the repos that most need these
+// entries are the ones where the files were committed before the CLI ignored them. Returns the
+// entries (as given) that have tracked files under them, so the caller can print the one hint
+// that fixes it (`git rm -r --cached …`). Empty when git is absent or cwd is not a repo.
+export function alreadyTracked(cwd: string, entries: string[]): string[] {
+  if (entries.length === 0) return []
+  try {
+    const r = spawnSync('git', ['ls-files', '-z', '--', ...entries], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    if (r.status !== 0 || !r.stdout) return []
+    const tracked = r.stdout.split('\0').filter(Boolean)
+    return entries.filter((e) => tracked.some((t) => t === e || t.startsWith(e.endsWith('/') ? e : `${e}/`)))
+  } catch {
+    return []
+  }
+}
+
+/** The one-line hint for `alreadyTracked` hits, or null when there are none. */
+export function untrackHint(tracked: string[]): string | null {
+  return tracked.length ? `  already tracked by git — to stop committing: git rm -r --cached ${tracked.join(' ')}` : null
+}

src/observe/hook.ts

@@ -1,7 +1,7 @@
 // PostToolUse hook: reads a tool-use event on stdin (Claude Code / Codex), scans every string
 // surface for credential exposure, and appends findings to ./.insta/audit.jsonl. Ported from firth.
 import { appendFileSync, mkdirSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { scanEvent, type ToolEvent } from './scanner.js'
 
@@ -34,10 +34,23 @@ async function readStdin(): Promise<string> {
   return Buffer.concat(chunks).toString('utf8')
 }
 
+// Where findings go. The materialized hook lives at <project root>/.insta/observe/hook.js, so its
+// own entry path names the linked project root — the one directory whose .insta/audit.jsonl is
+// gitignored and that `insta observe report` reads. Anything else (the harness's project-dir env,
+// the event cwd) is only a guess: Codex passes the SESSION cwd, which in a monorepo can be a
+// subdirectory of the project, and writing there would leave an unignored audit log behind.
+export function projectRootFor(entry: string | undefined, env: NodeJS.ProcessEnv, eventCwd: string | undefined): string {
+  if (entry) {
+    const dir = resolve(dirname(entry))
+    if (basename(dir) === 'observe' && basename(dirname(dir)) === '.insta') return dirname(dirname(dir))
+  }
+  return env.CLAUDE_PROJECT_DIR || eventCwd || '.'
+}
+
 export async function main(): Promise<void> {
   let event: ToolEvent
   try { event = JSON.parse(await readStdin()) } catch { process.exit(0) }
-  const base = process.env.CLAUDE_PROJECT_DIR || (event.cwd as string) || '.'
+  const base = projectRootFor(process.argv[1], process.env, event.cwd as string | undefined)
   try { recordFindings(event, base) } catch (e) { process.stderr.write(`insta-observe: ${e instanceof Error ? e.message : e}\n`) }
   process.exit(0)
 }

src/observe/install.ts

@@ -3,8 +3,16 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { alreadyTracked, ensureGitignore } from '../gitignore.js'
 
 const MARKER = 'insta-observe'
+
+// What the hook leaves under ./.insta that is machine-local, not project source: observe/ is a
+// copy of this CLI version's hook + scanner (regenerated by every `project link`), and
+// audit.jsonl is this machine's findings (fingerprints + redacted context — `insta observe sync`
+// is the share path). ./.insta/project.json stays committable: it is the team's project binding.
+const LOCAL_PATHS = ['.insta/observe/', '.insta/audit.jsonl']
+const GITIGNORE_COMMENT = '# InstaCloud: local observe-hook state (regenerated per machine, not source)'
 const DEFAULT_ASSET_DIR = dirname(fileURLToPath(import.meta.url)) // built: cli/dist/observe
 
 function cliVersion(): string {
@@ -65,18 +73,55 @@ function claudeEntry(): Group {
   return { matcher: '*', hooks: [{ type: 'command',
     command: `[ ! -f ${hook} ] || node ${hook}`, timeout: 15, _insta: MARKER }] }
 }
-function codexEntry(cwd: string): Group {
-  const abs = join(cwd, '.insta', 'observe', 'hook.js') // Codex doesn't expand ${CLAUDE_PROJECT_DIR}; use an absolute path
-  return { matcher: '*', hooks: [{ type: 'command', command: `node ${JSON.stringify(abs)}`, timeout: 15, _insta: MARKER }] }
+// The Codex hook command. Constraints that rule out every simpler form:
+//  - no absolute path: it made .codex/hooks.json machine-specific (a teammate committing it shipped
+//    /Users/<author>/… to every clone, where node failed after each tool call);
+//  - not `git rev-parse --show-toplevel`: the insta project root is wherever `project link` ran,
+//    which in a monorepo is below the git root (`findProjectRoot` climbs for .insta/project.json
+//    for exactly that reason), so the hook would silently never fire there;
+//  - no POSIX shell syntax: with no `commandWindows` override Codex hands `command` verbatim to
+//    cmd.exe on Windows, where `[ ! -f … ]` / `$(…)` are parse errors — after every tool call.
+// So: one shell-neutral `node -e` that climbs from the session cwd (Codex runs project hooks with
+// the project as cwd) to the nearest .insta/observe/hook.js and runs it with stdin passed through;
+// a fresh clone with no ./.insta anywhere above is a silent no-op. The script must stay free of
+// characters either shell rewrites inside double quotes: `$` and backticks (sh), `%` and `!`
+// (cmd.exe), and `"` (both). Codex has each user trust the entry before it runs, so shareable is safe.
+const CODEX_HOOK_SCRIPT = [
+  "const f=require('fs'),p=require('path'),c=require('child_process');",
+  'let d=process.cwd();',
+  'for(;;){',
+  "const h=p.join(d,'.insta/observe/hook.js');",
+  "if(f.existsSync(h)){const r=c.spawnSync(process.execPath,[h],{stdio:'inherit'});process.exitCode=r.status===null?1:r.status;break}",
+  'const u=p.dirname(d);if(u===d)break;d=u}',
+].join('')
+
+function codexEntry(): Group {
+  return { matcher: '*', hooks: [{ type: 'command',
+    command: `node -e "${CODEX_HOOK_SCRIPT}"`, timeout: 15, _insta: MARKER }] }
+}
+
+export type ObserveInstall = {
+  claude: boolean
+  codex: boolean
+  /** .gitignore entries added by this call (empty on a re-link). */
+  ignored: string[]
+  /** LOCAL_PATHS entries git already tracks — an ignore entry can't help those; see `untrackHint`. */
+  tracked: string[]
 }
 
-export function installObserve(opts: { cwd: string; assetDir?: string }): { claude: boolean; codex: boolean } {
+export function installObserve(opts: { cwd: string; assetDir?: string }): ObserveInstall {
   materialize(opts.cwd, opts.assetDir ?? DEFAULT_ASSET_DIR) // hook required → let a missing asset throw to the caller
+  // Ignore the local state in the same step that creates it, so nobody discovers it via
+  // `git status`. Best-effort: an unwritable .gitignore must not fail the hook install.
+  // (Uninstall deliberately leaves the entries: a stale audit.jsonl should stay ignored.)
+  let ignored: string[] = []
+  try { ignored = ensureGitignore(opts.cwd, LOCAL_PATHS, GITIGNORE_COMMENT) } catch { /* keep going */ }
+  const tracked = alreadyTracked(opts.cwd, LOCAL_PATHS)
   let claude = false
   let codex = false
   try { registerHarness(join(opts.cwd, '.claude', 'settings.json'), claudeEntry()); claude = true } catch { /* skip malformed */ }
-  try { registerHarness(join(opts.cwd, '.codex', 'hooks.json'), codexEntry(opts.cwd)); codex = true } catch { /* skip malformed */ }
-  return { claude, codex }
+  try { registerHarness(join(opts.cwd, '.codex', 'hooks.json'), codexEntry()); codex = true } catch { /* skip malformed */ }
+  return { claude, codex, ignored, tracked }
 }
 
 export function uninstallObserve(cwd: string): void {