Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Data-root resolution + worktree-checkout detection.
*
* PortOS derives its "install root" (the directory that contains `data/`,
* `data.reference/`, `scripts/`) from where the executing file lives
* (`import.meta.url`). That silently breaks when a process boots from inside a
* CoS agent's git worktree (`data/cos/worktrees/agent-<id>`): the checkout only
* contains git-tracked files, so the gitignored `data/` runtime tree is empty,
* and boot migrations resolve against a nonexistent path and crash (#1947).
*
* `resolveInstallRoot()` lets a real launch pin the root explicitly via the
* `PORTOS_DATA_ROOT` env var, independent of the executing file's location, so
* even a process booted from inside a worktree still resolves to the real
* install. `isWorktreeRoot()` is the defensive backstop: detect a
* worktree-rooted process so callers (boot migrations) can skip work that
* assumes the real install tree instead of crashing.
*/
import { existsSync } from 'fs';
import { dirname, isAbsolute, join, resolve as resolvePath, sep } from 'path';
import { fileURLToPath } from 'url';
/** Env var a real launch sets to pin the install root (see ecosystem.config.cjs). */
export const DATA_ROOT_ENV = 'PORTOS_DATA_ROOT';
/**
* Marker file that declares an install root DISPOSABLE — a throwaway tree a
* harness created for one process (the server boot smoke, #8343) and deletes
* afterwards. Such a root holds no live data, so it is the one pin a
* worktree-executing process may honor: the leak-safety rule below exists to
* keep worktree code off the LIVE install, and a live install never carries
* this marker.
*/
export const DISPOSABLE_ROOT_MARKER = '.portos-disposable-root';
/** True when `rootDir` carries the disposable-root marker. */
export const isDisposableRoot = (rootDir) => existsSync(join(rootDir, DISPOSABLE_ROOT_MARKER));
/**
* The executing checkout's root, derived from a caller's `import.meta.url`
* (two directories up from wherever that module physically lives). Single
* source of truth for this depth assumption — `lib/paths.js`'s `CODE_ROOT`
* and any code that must independently re-derive the real (non-test-mocked)
* install root, such as `userActions.js`'s data-root guard, both resolve it
* through here so the two can never silently drift apart if this formula
* ever changes.
*
* @param {string} moduleUrl the caller's `import.meta.url`
* @returns {string} absolute path two directories above the caller's file
*/
export function resolveCodeRootForModule(moduleUrl) {
return join(dirname(fileURLToPath(moduleUrl)), '../..');
}
/**
* Resolve the PortOS install root (the parent of `data/` and `data.reference/`).
*
* Prefers an explicit `PORTOS_DATA_ROOT` env var (set at a real launch in
* `ecosystem.config.cjs`) over the caller's `import.meta.url`-derived fallback,
* pinning the primary install's root independent of the executing-file location.
* Returns `fallbackRoot` unchanged when the env var is unset or blank —
* preserving the existing behavior for installs that never set it (backward
* compatible).
*
* The var is set ONLY on the `portos-server` app (not the shared `BASE_ENV`), so
* the `portos-cos` runner — which spreads its `process.env` into agent CLI
* children — never carries it into worktree agents. As belt-and-suspenders, this
* resolver ALSO refuses the pin whenever the executing location (`fallbackRoot`)
* is itself a worktree checkout: even a leaked `PORTOS_DATA_ROOT` can't make
* worktree-version code resolve `PATHS.data` to the LIVE install and read/write
* real data. In that case resolution stays on the worktree path, where the
* migration backstop safely skips and `PATHS.data` points at the worktree's own
* (empty) tree — no crash, no live-data corruption.
*
* @param {string} fallbackRoot absolute path derived from the caller's location
* @returns {string} the install root to use
*/
export function resolveInstallRoot(fallbackRoot) {
// Leak-safety (#1947): a process whose CODE physically lives inside a worktree
// checkout must NEVER honor a PORTOS_DATA_ROOT pin. The var is inherited by
// long-lived PM2 processes and can leak into agent child envs (spread of
// process.env), so a worktree-launched command could otherwise resolve
// PATHS.data to the LIVE install and let worktree-version code read/write real
// data. When the fallback (the executing location) is itself a worktree, ignore
// the override and stay on the worktree path — where the migration backstop
// safely skips and PATHS.data points at the worktree's own (empty) tree.
//
// The single exception is a pin to a DISPOSABLE root (marker file above): it
// holds no live data by construction, so honoring it from a worktree is what
// lets `npm run smoke` stay hermetic there too instead of writing into the
// worktree's own `data/`.
const override = process.env[DATA_ROOT_ENV];
if (typeof override !== 'string' || override.trim() === '') return fallbackRoot;
const trimmed = override.trim();
const resolved = isAbsolute(trimmed) ? trimmed : resolvePath(trimmed);
// Symmetric leak-safety: never let the data root resolve INTO a worktree,
// whether the worktree path came from the executing location (below) or a
// misconfigured override. A worktree has no runtime data/ tree, so honoring
// such an override would strand the real process on an empty tree.
if (isWorktreeRoot(resolved)) return fallbackRoot;
if (isWorktreeRoot(fallbackRoot) && !isDisposableRoot(resolved)) return fallbackRoot;
return resolved;
}
/**
* True when `rootDir` is a CoS agent worktree checkout rather than the real
* install — its path lives under `data/cos/worktrees/`. Such a checkout has no
* gitignored `data/` runtime tree, so boot migrations (and any pass that
* assumes the real install's `data/`/`data.reference/`) must skip it instead of
* crashing on ENOENT.
*
* We key ONLY on the `data/cos/worktrees/` path segment, not on "does `data/`
* exist" — a worktree checkout still ships `data/.gitkeep`, and a genuinely
* fresh real install legitimately has an empty `data/` on first boot (the
* migration runner creates it), so a presence check would false-positive on
* fresh installs and skip their migrations.
*
* @param {string} rootDir candidate install root
* @returns {boolean}
*/
export function isWorktreeRoot(rootDir) {
if (typeof rootDir !== 'string' || rootDir === '') return false;
const normalized = resolvePath(rootDir);
const segment = `${sep}${['data', 'cos', 'worktrees'].join(sep)}`;
return normalized.includes(`${segment}${sep}`) || normalized.endsWith(segment);
}