@logicseek/hello-cc 1.0.5 → 1.1.0-rc.3

package/lib/runtime/state.mjs

@@ -1,13 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { performance } from 'node:perf_hooks';
 import { compareProcessIdentity, inspectProcessIdentity } from '../process/identity.mjs';
 import { CliError } from '../shared/errors.mjs';
 import { withFileLock } from '../shared/file-lock.mjs';
 import { writeJsonSafe } from '../shared/json-file.mjs';
+import { readPrivateTextFile } from './private-file.mjs';
+import { resolveProjectDatabase, secureExistingProjectStateDirectory } from './project-path.mjs';
 import {
-  globalRuntimePath,
-  runtimePath
+  globalRuntimePath
 } from './paths.mjs';
 import { runtimeHttpRequest } from '../web/runtime.mjs';
 import { API_VERSION } from '../web/api-version.mjs';
@@ -16,6 +18,18 @@ const DEFAULT_PRODUCT_NAME = 'hello-cc';
 const DEFAULT_CLI_NAME = 'hcc';
 export const RUNTIME_POINTER_UNKNOWN_GRACE_MS = 120_000;
 
+function validatedProjectRuntimeFile(root, { create = false } = {}) {
+  const state = create
+    ? resolveProjectDatabase({
+      root, db: path.join(path.resolve(root), '.hello-cc', 'runtime.json'), createStateDir: true
+    })
+    : secureExistingProjectStateDirectory(root);
+  // Validate this target, not an unused default mesh.db (custom/external DBs
+  // remain supported). Keep the returned state route instead of resolving a
+  // mutable root alias again after validation.
+  return path.join(state.stateDir, 'runtime.json');
+}
+
 function completeProcessIdentity(value) {
   return compareProcessIdentity(value, value) === 'live';
 }
@@ -77,11 +91,15 @@ export function reclaimRuntimePointerFiles(files, {
   reclaimUnknown = true,
   dryRun = false,
   onReclaim = null,
+  expectedIdentity = null,
   withLock = withFileLock
 } = {}) {
   if (typeof reclaimUnknown !== 'boolean') {
     throw new TypeError('reclaimUnknown must be a boolean');
   }
+  if (expectedIdentity !== null && !completeProcessIdentity(expectedIdentity)) {
+    throw new TypeError('expectedIdentity must be a complete process identity');
+  }
   let blocked = false;
   let reclaimed = 0;
   const outcomes = [];
@@ -107,6 +125,16 @@ export function reclaimRuntimePointerFiles(files, {
         const raw = fs.readFileSync(file, 'utf8');
         let runtime = null;
         try { runtime = JSON.parse(raw); } catch {}
+        if (expectedIdentity !== null) {
+          const currentIdentity = runtimeIdentityEvidence(runtime).identity;
+          if (Number(runtime?.pid) !== expectedIdentity.pid ||
+              compareProcessIdentity(expectedIdentity, currentIdentity) !== 'live' ||
+              currentIdentity.commandHash !== expectedIdentity.commandHash) {
+            blocked = true;
+            record({ state: 'unknown', action: 'blocked', reason: 'owner_changed' });
+            return;
+          }
+        }
         const timing = runtimePointerAge(stat, nowMs(), unknownGraceMs);
         const evidence = classifyRuntimePointer(runtime, {
           inspect,
@@ -200,9 +228,10 @@ function runtimeMetadataMatchesPointer(runtime, metadata) {
 
 export function readGlobalRuntimeFile() {
   const file = globalRuntimePath();
-  if (!fs.existsSync(file)) return null;
+  const raw = readPrivateTextFile(file);
+  if (raw === null) return null;
   try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
+    return JSON.parse(raw);
   } catch {
     // Do not delete on a parse failure: a torn/partial write must not orphan a
     // healthy runtime pointer. Leave it for health probing / restart to reclaim.
@@ -217,7 +246,7 @@ export function writeGlobalRuntime(runtime) {
 }
 
 export function writeRuntime(ctx, runtime) {
-  const file = runtimePath(ctx);
+  const file = validatedProjectRuntimeFile(ctx.root, { create: true });
   withFileLock(file, (lockedFile) => writeJsonSafe(lockedFile, runtime, { mode: 0o600 }));
   return file;
 }
@@ -235,10 +264,11 @@ export function readRuntime(ctx, opts = {}) {
       source: 'env'
     };
   }
-  const file = runtimePath(ctx);
-  if (fs.existsSync(file)) {
+  const file = validatedProjectRuntimeFile(ctx.root);
+  const raw = readPrivateTextFile(file);
+  if (raw !== null) {
     try {
-      const runtime = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const runtime = JSON.parse(raw);
       if (!runtime.base_url) throw new Error('missing base_url');
       if (!runtimePointerMatchesCurrentProcess(runtime, { inspect: inspectRuntimeProcessIdentity })) {
         throw new Error('runtime process identity does not match');
@@ -264,9 +294,9 @@ export function readRuntime(ctx, opts = {}) {
 }
 
 export function readRuntimeFile(ctx) {
-  const file = runtimePath(ctx);
-  if (!fs.existsSync(file)) return null;
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  const file = validatedProjectRuntimeFile(ctx.root);
+  const raw = readPrivateTextFile(file);
+  return raw === null ? null : JSON.parse(raw);
 }
 
 export async function probeRuntime(runtime) {
@@ -306,30 +336,42 @@ export async function readHealthyGlobalRuntime() {
   }
 }
 
-export function clearRuntime(ctx, pid = process.pid) {
-  const file = runtimePath(ctx);
-  try {
+export function clearRuntime(ctx, pid = process.pid, {
+  nonblocking = false, clearGlobal = true, expectedIdentity = null,
+  deadline = Infinity, monotonicNow = () => performance.now()
+} = {}) {
+  if (expectedIdentity !== null && !completeProcessIdentity(expectedIdentity)) {
+    throw new TypeError('expectedIdentity must be a complete process identity');
+  }
+  function clearOwnedFile(file) {
+    if (monotonicNow() >= deadline) return;
     withFileLock(file, (lockedFile) => {
-      if (!fs.existsSync(lockedFile)) return;
+      if (monotonicNow() >= deadline) return;
+      ctx.rootIdentity?.assertUnchanged();
+      const raw = readPrivateTextFile(lockedFile);
+      if (raw === null) return;
       try {
-        const runtime = JSON.parse(fs.readFileSync(lockedFile, 'utf8'));
+        const runtime = JSON.parse(raw);
+        if (expectedIdentity !== null) {
+          const currentIdentity = runtimeIdentityEvidence(runtime).identity;
+          if (runtime.pid !== expectedIdentity.pid ||
+              compareProcessIdentity(expectedIdentity, currentIdentity) !== 'live' ||
+              currentIdentity.commandHash !== expectedIdentity.commandHash) return;
+        }
         if (runtime.pid === pid) fs.rmSync(lockedFile, { force: true });
       } catch {
         // Leave an unparseable pointer in place: only remove when we can confirm
         // it belongs to this pid, so a torn write never deletes another runtime's file.
       }
-    });
+    }, { nonblocking });
+  }
+  try {
+    if (monotonicNow() >= deadline) return;
+    ctx.rootIdentity?.assertUnchanged();
+    clearOwnedFile(validatedProjectRuntimeFile(ctx.root));
   } catch {}
-  const globalFile = globalRuntimePath();
+  if (!clearGlobal || monotonicNow() >= deadline) return;
   try {
-    withFileLock(globalFile, (lockedFile) => {
-      if (!fs.existsSync(lockedFile)) return;
-      try {
-        const runtime = JSON.parse(fs.readFileSync(lockedFile, 'utf8'));
-        if (runtime.pid === pid) fs.rmSync(lockedFile, { force: true });
-      } catch {
-        // Same as above: do not blind-delete a torn global runtime pointer.
-      }
-    });
+    clearOwnedFile(globalRuntimePath());
   } catch {}
 }

package/lib/shared/automatic-result-key.mjs

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+
+export function automaticResultKey({ executorId, threadId, turnId, kind, itemId = null }) {
+  const identity = [executorId, threadId, turnId, kind, itemId];
+  return `automatic:${kind}:${createHash('sha256').update(JSON.stringify(identity)).digest('hex')}`;
+}

package/lib/shared/json-file.mjs

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -8,11 +9,59 @@ export function readJsonSafe(filePath) {
 
 export function writeJsonSafe(filePath, data, opts = {}) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  const tmpPath = filePath + '.tmp.' + process.pid;
-  const writeOpts = opts.mode !== undefined ? { mode: opts.mode } : undefined;
-  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', writeOpts);
-  fs.renameSync(tmpPath, filePath);
-  if (opts.mode !== undefined) {
-    try { fs.chmodSync(filePath, opts.mode); } catch {}
+  const tmpPath = `${filePath}.tmp.${process.pid}.${randomBytes(16).toString('hex')}`;
+  const contents = JSON.stringify(data, null, 2) + '\n';
+  let fd = null;
+  let opened = null;
+  let renamed = false;
+  try {
+    fd = fs.openSync(tmpPath, fs.constants.O_WRONLY | fs.constants.O_CREAT |
+      fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
+    opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.nlink !== 1 ||
+        (typeof process.geteuid === 'function' && opened.uid !== process.geteuid())) {
+      throw new Error(`unsafe JSON temporary file: ${tmpPath}`);
+    }
+    if (process.platform !== 'win32') fs.fchmodSync(fd, 0o600);
+    const privateStat = fs.fstatSync(fd);
+    if (!privateStat.isFile() || privateStat.nlink !== 1 ||
+        privateStat.dev !== opened.dev || privateStat.ino !== opened.ino ||
+        (typeof process.geteuid === 'function' && privateStat.uid !== process.geteuid()) ||
+        (process.platform !== 'win32' && (privateStat.mode & 0o777) !== 0o600)) {
+      throw new Error(`unsafe JSON temporary file: ${tmpPath}`);
+    }
+    fs.writeFileSync(fd, contents, 'utf8');
+    if (opts.mode !== undefined && opts.mode !== 0o600 && process.platform !== 'win32') {
+      fs.fchmodSync(fd, opts.mode);
+    }
+    const ready = fs.fstatSync(fd);
+    if (!ready.isFile() || ready.nlink !== 1 ||
+        ready.dev !== opened.dev || ready.ino !== opened.ino ||
+        (typeof process.geteuid === 'function' && ready.uid !== process.geteuid()) ||
+        (process.platform !== 'win32' && (ready.mode & 0o777) !== (opts.mode ?? 0o600))) {
+      throw new Error(`unsafe JSON temporary file: ${tmpPath}`);
+    }
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    const current = fs.lstatSync(tmpPath);
+    if (!current.isFile() || current.nlink !== 1 ||
+        current.dev !== opened.dev || current.ino !== opened.ino ||
+        (typeof process.geteuid === 'function' && current.uid !== process.geteuid()) ||
+        (process.platform !== 'win32' && (current.mode & 0o777) !== (opts.mode ?? 0o600))) {
+      throw new Error(`JSON temporary file changed before rename: ${tmpPath}`);
+    }
+    fs.renameSync(tmpPath, filePath);
+    renamed = true;
+  } finally {
+    if (fd !== null) fs.closeSync(fd);
+    if (!renamed && opened) {
+      try {
+        const current = fs.lstatSync(tmpPath);
+        if (current.dev === opened.dev && current.ino === opened.ino) fs.unlinkSync(tmpPath);
+      } catch {
+        // Preserve the write failure. Any remaining temp file is private.
+      }
+    }
   }
 }

package/lib/shared/redact.mjs

@@ -6,6 +6,7 @@ function isSecretKey(key) {
   return normalized === 'authorization' ||
     normalized === 'cookie' ||
     normalized === 'setcookie' ||
+    /^hccsid(?:v2https?\d+)?$/.test(normalized) ||
     normalized.includes('secret') ||
     normalized.endsWith('password') ||
     normalized.endsWith('credential') ||
@@ -21,7 +22,7 @@ function redactString(value) {
     .replace(/\bBearer\s+[^\s,;]+/gi, `Bearer ${REDACTED}`)
     .replace(/(--token(?:=|\s+))(?:"[^"]*"|'[^']*'|[^\s]+)/gi, `$1${REDACTED}`)
     .replace(/([?&](?:token|access_token|api_key)=)[^&#\s]*/gi, `$1${REDACTED}`)
-    .replace(/(hcc_sid=)[^;\s]*/gi, `$1${REDACTED}`);
+    .replace(/(hcc_sid(?:_v2_https?_\d+)?=)[^;\s]*/gi, `$1${REDACTED}`);
 }
 
 export function redactCliArgs(args) {

package/lib/ui/help.mjs

@@ -21,7 +21,8 @@ Commands:
   down                         Stop the running hello-cc web runtime
   update                       Update the global npm install of hello-cc
   uninstall                    Remove hooks, shims, and optional project data
-  init                         Initialize .hello-cc/mesh.db and guidance
+  init                         Initialize private managed mesh.db and guidance
+  migrate-state --offline --yes Copy stopped legacy state to private per-user storage
   register --peer ID           Register or update a peer session identity
   join --peer ID               Register this shell and print eval-able env
   env --peer ID                Print eval-able HCC_PEER/HCC_ROOT/HCC_DB exports
@@ -405,9 +406,10 @@ Usage:
 Stops the current project runtime and removes user-level hello-cc integrations:
 Claude/Codex hooks, claude/codex shims, and the shell PATH entry for shims.
 
-With --purge --yes, also removes current project data:
-  .hello-cc/
-  hello-cc blocks from CLAUDE.md and AGENTS.md
+With --purge --yes, also removes the selected managed project state directory
+(project-local for stable roots, otherwise under ~/.hello-cc/projects/) and
+hello-cc blocks from CLAUDE.md and AGENTS.md. An old directory retained by
+offline migration is not removed.
 `);
     },
 

package/lib/web/agent-defaults.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../shared/errors.mjs';
+import { tx } from '../db/schema.mjs';
+
+const META_KEY = 'web_agent_defaults_v1';
+const PROVIDERS = ['codex', 'claude', 'dsh'];
+
+function invalid(message) { return new CliError('BAD_REQUEST', message); }
+function plainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function exactKeys(value, keys) {
+  return plainObject(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+function initialDefaults() {
+  return { revision: 0, defaultProvider: 'codex', providers: Object.fromEntries(PROVIDERS.map(provider => [provider, { model: null, cwd: '.' }])) };
+}
+function normalizeModel(value) {
+  if (value === null) return null;
+  if (typeof value !== 'string' || value.length > 256 || /[\x00-\x1f\x7f]/.test(value)) throw invalid('Model must be null or a name of at most 256 characters without control characters');
+  return value.trim() || null;
+}
+function relativeCwd(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 4096 || /[\\:\x00-\x1f\x7f]/.test(value) ||
+      path.posix.isAbsolute(value.trim()) || path.win32.isAbsolute(value.trim()) || value.trim().split('/').includes('..')) {
+    throw invalid('Default working directory must be a project-relative directory, using . for the project root');
+  }
+  return path.posix.normalize(value.trim()).replace(/\/$/, '') || '.';
+}
+function assertRoot(ctx) { ctx.rootIdentity?.assertUnchanged(); }
+function existingCwd(ctx, relative) {
+  assertRoot(ctx);
+  let root, target;
+  try {
+    root = fs.realpathSync(ctx.root); target = fs.realpathSync(path.resolve(root, relative));
+    if (!fs.statSync(target).isDirectory()) throw new Error('not a directory');
+  } catch { throw invalid('Default working directory must already exist inside the selected project'); }
+  assertRoot(ctx);
+  const fromRoot = path.relative(root, target);
+  if (fromRoot === '..' || fromRoot.startsWith('..' + path.sep) || path.isAbsolute(fromRoot)) {
+    throw new CliError('PROJECT_PATH_FORBIDDEN', 'Default working directory must stay inside the selected project');
+  }
+  const canonical = fromRoot.split(path.sep).join('/') || '.';
+  if (relativeCwd(canonical) !== canonical) throw invalid('The resolved default directory cannot be represented as a stable project-relative setting');
+  return canonical;
+}
+function validateDocument(value) {
+  if (!exactKeys(value, ['revision', 'defaultProvider', 'providers']) ||
+      !Number.isSafeInteger(value.revision) || value.revision < 0 || Object.is(value.revision, -0) ||
+      !PROVIDERS.includes(value.defaultProvider) || !exactKeys(value.providers, PROVIDERS)) {
+    throw invalid('Agent defaults require a safe revision, a native provider and complete codex, claude and dsh settings');
+  }
+  const providers = {};
+  for (const provider of PROVIDERS) {
+    const setting = value.providers[provider];
+    if (!exactKeys(setting, ['model', 'cwd'])) throw invalid('Each provider setting accepts only model and cwd');
+    providers[provider] = { model: normalizeModel(setting.model), cwd: relativeCwd(setting.cwd) };
+  }
+  return { revision: value.revision, defaultProvider: value.defaultProvider, providers };
+}
+function storedDefaults(db) {
+  const row = db.prepare('SELECT value FROM meta WHERE key=?').get(META_KEY);
+  if (!row) return initialDefaults();
+  try {
+    if (typeof row.value !== 'string' || row.value.length > 16384) throw new Error('invalid settings');
+    const value = validateDocument(JSON.parse(row.value));
+    if (value.revision === 0) throw new Error('invalid saved revision');
+    return value;
+  } catch {
+    throw new CliError('AGENT_DEFAULTS_INVALID', 'Saved Agent defaults are invalid; inspect the project configuration before saving or creating a worker');
+  }
+}
+
+/** HCC project settings only. Provider accounts, processes and config files are never touched. */
+export function createAgentDefaults({ connectWebProject }) {
+  function readAgentDefaults(ctx) {
+    assertRoot(ctx);
+    const db = connectWebProject(ctx);
+    try { const value = storedDefaults(db); assertRoot(ctx); return value; }
+    finally { db.close(); }
+  }
+  function saveAgentDefaults(ctx, input) {
+    const requested = validateDocument(input);
+    if (requested.revision === Number.MAX_SAFE_INTEGER) throw invalid('Agent defaults revision is exhausted');
+    assertRoot(ctx);
+    const db = connectWebProject(ctx);
+    try {
+      return tx(db, () => {
+        assertRoot(ctx);
+        const current = storedDefaults(db);
+        if (requested.revision !== current.revision) throw new CliError('AGENT_DEFAULTS_CONFLICT', 'Agent defaults changed in another view; reload them before saving your draft');
+        const providers = {};
+        for (const provider of PROVIDERS) providers[provider] = { model: requested.providers[provider].model,
+          cwd: existingCwd(ctx, requested.providers[provider].cwd) };
+        const saved = { revision: current.revision + 1, defaultProvider: requested.defaultProvider, providers };
+        assertRoot(ctx);
+        db.prepare('INSERT INTO meta(key,value) VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value')
+          .run(META_KEY, JSON.stringify(saved));
+        assertRoot(ctx);
+        return saved;
+      });
+    } finally { db.close(); }
+  }
+  function resolveNativeDefaults(ctx, input) {
+    const saved = readAgentDefaults(ctx), kind = input.kind === undefined ? saved.defaultProvider : input.kind;
+    if (!PROVIDERS.includes(kind)) throw invalid('Use native provider codex, claude or dsh');
+    const setting = saved.providers[kind], model = input.model === undefined ? setting.model : normalizeModel(input.model);
+    return { ...input, kind, cwd: input.cwd === undefined ? setting.cwd : input.cwd, model: model === null ? undefined : model };
+  }
+  return { readAgentDefaults, saveAgentDefaults, resolveNativeDefaults };
+}

package/lib/web/auto-attach.mjs

@@ -11,7 +11,7 @@ import { adoptionPaused } from './adoption-state.mjs';
 
 export function createAutoAttach(deps) {
   const {
-    ctx, sessions,
+    ctx, sessions, isStopping = () => false,
     connectWebProject, now, addEvent,
     reconcileRunningPeerBindings,
     ACTIVE_PEER_TTL, redactedLogText, sessionsForProject,
@@ -66,6 +66,7 @@ export function createAutoAttach(deps) {
   }
 
   function reconcileRunningBindings(projectCtx = ctx, panes = null) {
+    if (isStopping()) return null;
     const db = connectWebProject(projectCtx);
     try {
       const tmuxPanes = Array.isArray(panes) ? panes : listTmuxPanesOnce();
@@ -86,7 +87,7 @@ export function createAutoAttach(deps) {
   let autoAttachScanInFlight = false;
 
   function scanAndAttachDetectedPeers() {
-    if (autoAttachScanInFlight) return;
+    if (isStopping() || autoAttachScanInFlight) return;
     autoAttachScanInFlight = true;
     let db = null;
     try {

package/lib/web/browser/contracts.d.ts

@@ -0,0 +1,10 @@
+/** Server authority; browser drafts/selection/scroll positions are separate. */
+export type Provider = 'codex' | 'claude' | 'dsh' | 'shell';
+export interface Capabilities { send?: boolean; steer?: boolean; interrupt?: boolean; approval?: boolean; commands?: boolean; [name: string]: boolean | undefined }
+export interface Approval { id: string; type: string; turnId?: string; requestId?: string; status?: string }
+export interface Delivery { message_id: string; submission_id?: string; turn_id?: string; state: string; error?: string }
+export interface Item { id: string; type: string; text?: string; status?: string }
+export interface Turn { id: string; status: string; items: Item[] }
+export interface Session { id: string; root: string; type: 'native' | 'app-server' | 'tmux' | 'pty'; kind: Provider; status: string; executor_id?: string; capabilities?: Capabilities }
+export interface PaneView { project: string; session: string | null; draft: string; scrollTop: number; selectedTab: 'conversation' | 'trace' }
+export interface StateSyncFrame { type: 'state_sync'; protocol: 1; mode: 'snapshot' | 'patch'; channel: 'codex' | 'native'; root: string; sessionId: string; executorId: string; generation: string; revision: number; baseRevision?: number; state?: unknown; operations?: unknown[] }