@viewportai/daemon 0.1.0

package/dist/tracking/git-tracker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GitTracker — git-backed run tracking with worktree isolation.
+ *
+ * Creates a git worktree per session, micro-commits on configurable tool calls,
+ * and supports rollback, branch-retry, and squash-merge operations.
+ *
+ * This is the most complex module in the daemon. It directly manages git state
+ * via child_process — no git library dependency.
+ */
+import type { RunTracker } from '../core/interfaces.js';
+import type { SessionMessage, Step, GitTrackerConfig } from '../core/types.js';
+export declare class GitTracker implements RunTracker {
+    private config;
+    private worktreePath;
+    private projectPath;
+    private branch;
+    private stepCounter;
+    private commitCount;
+    private _steps;
+    private commitQueue;
+    private tornDown;
+    /** Callback fired after each successful commit. */
+    onStepCommitted?: (step: Step) => void;
+    private readonly _sessionId;
+    constructor(config: GitTrackerConfig, sessionId: string);
+    get steps(): ReadonlyArray<Step>;
+    /** Await all pending commits. Useful for testing. */
+    flush(): Promise<void>;
+    /** Flush any pending commits. Called before teardown on crash/end. */
+    flushPendingCommits(): Promise<void>;
+    setup(_sessionId: string, projectPath: string): Promise<string>;
+    onMessage(msg: SessionMessage): void;
+    rollback(toSha: string): Promise<void>;
+    branchRetry(fromSha: string): Promise<string>;
+    squashMerge(targetBranch: string, commitMessage: string): Promise<void>;
+    teardown(): Promise<void>;
+    getDiff(sha: string): Promise<string>;
+    getStepDiffs(): Promise<Array<{
+        step: number;
+        sha: string;
+        diff: string;
+    }>>;
+    getSummaryDiff(): Promise<string>;
+    private shouldCommit;
+    private enqueueCommit;
+    private doCommit;
+    private describeStep;
+    private writeStepLog;
+    private ensureWorktree;
+    private git;
+}
+//# sourceMappingURL=git-tracker.d.ts.map

package/dist/tracking/git-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-tracker.d.ts","sourceRoot":"","sources":["../../src/tracking/git-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAU/E,qBAAa,UAAW,YAAW,UAAU;IAgBzC,OAAO,CAAC,MAAM;IAfhB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,QAAQ,CAAS;IAEzB,mDAAmD;IACnD,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAEvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAG1B,MAAM,EAAE,gBAAgB,EAChC,SAAS,EAAE,MAAM;IAMnB,IAAI,KAAK,IAAI,aAAa,CAAC,IAAI,CAAC,CAE/B;IAED,qDAAqD;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,sEAAsE;IAChE,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBrE,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAsB9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW7C,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCvE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBzB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYrC,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAW3E,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAyBvC,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,aAAa;YAUP,QAAQ;IA8CtB,OAAO,CAAC,YAAY;YAiBN,YAAY;IA0B1B,OAAO,CAAC,cAAc;YAMR,GAAG;CAQlB"}

package/dist/tracking/git-tracker.js

@@ -0,0 +1,277 @@
+/**
+ * GitTracker — git-backed run tracking with worktree isolation.
+ *
+ * Creates a git worktree per session, micro-commits on configurable tool calls,
+ * and supports rollback, branch-retry, and squash-merge operations.
+ *
+ * This is the most complex module in the daemon. It directly manages git state
+ * via child_process — no git library dependency.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { metrics } from '../core/metrics.js';
+import { logger } from '../core/logger.js';
+const log = logger.child({ module: 'git-tracker' });
+const execGit = promisify(execFile);
+const GIT_TIMEOUT_MS = 30_000;
+export class GitTracker {
+    config;
+    worktreePath = null;
+    projectPath = null;
+    branch;
+    stepCounter = 0;
+    commitCount = 0;
+    _steps = [];
+    commitQueue = Promise.resolve();
+    tornDown = false;
+    /** Callback fired after each successful commit. */
+    onStepCommitted;
+    _sessionId;
+    constructor(config, sessionId) {
+        this.config = config;
+        this._sessionId = sessionId;
+        this.branch = `${config.branchPrefix}${sessionId}`;
+    }
+    get steps() {
+        return this._steps;
+    }
+    /** Await all pending commits. Useful for testing. */
+    async flush() {
+        await this.commitQueue;
+    }
+    /** Flush any pending commits. Called before teardown on crash/end. */
+    async flushPendingCommits() {
+        await this.commitQueue;
+    }
+    async setup(_sessionId, projectPath) {
+        this.projectPath = projectPath;
+        // Verify this is a git repo
+        await this.git(['rev-parse', '--is-inside-work-tree'], projectPath);
+        // Compute worktree path
+        this.worktreePath = path.join(projectPath, this.config.worktreeRoot, this._sessionId);
+        // Ensure parent directory exists
+        await fs.mkdir(path.dirname(this.worktreePath), { recursive: true });
+        // Create worktree + branch
+        await this.git(['worktree', 'add', this.worktreePath, '-b', this.branch], projectPath);
+        return this.worktreePath;
+    }
+    onMessage(msg) {
+        if (this.tornDown)
+            return;
+        this.stepCounter++;
+        const step = {
+            step: this.stepCounter,
+            sha: null,
+            type: msg.type,
+            toolName: 'toolName' in msg ? msg.toolName : undefined,
+            description: this.describeStep(msg),
+            timestamp: msg.timestamp,
+        };
+        this._steps.push(step);
+        // Only commit on completed tool calls for configured tools
+        if (msg.type === 'tool_call_update' && msg.status === 'completed' && msg.toolName) {
+            if (this.shouldCommit(msg.toolName)) {
+                this.enqueueCommit(step);
+            }
+        }
+    }
+    async rollback(toSha) {
+        this.ensureWorktree();
+        await this.git(['reset', '--hard', toSha], this.worktreePath);
+        metrics.increment('git.rollbacks');
+    }
+    async branchRetry(fromSha) {
+        this.ensureWorktree();
+        const retryBranch = `${this.branch}-retry-${Date.now()}`;
+        const retryPath = `${this.worktreePath}-retry-${Date.now()}`;
+        await fs.mkdir(path.dirname(retryPath), { recursive: true });
+        await this.git(['worktree', 'add', retryPath, '-b', retryBranch, fromSha], this.projectPath);
+        return retryPath;
+    }
+    async squashMerge(targetBranch, commitMessage) {
+        this.ensureWorktree();
+        // Flush any pending commits first
+        await this.commitQueue;
+        if (targetBranch === this.branch) {
+            throw new Error('Target branch must differ from session branch');
+        }
+        // Keep all merge operations inside the session worktree so we never mutate
+        // the user's main working tree branch.
+        const targetRef = `refs/heads/${targetBranch}`;
+        const { stdout: targetShaRaw } = await this.git(['rev-parse', '--verify', targetRef], this.projectPath);
+        const targetSha = targetShaRaw.trim();
+        try {
+            await this.git(['checkout', '--detach', targetSha], this.worktreePath);
+            await this.git(['merge', '--squash', this.branch], this.worktreePath);
+            await this.git(['commit', '-m', commitMessage, '--author', this.config.commitAuthor], this.worktreePath);
+            const { stdout: mergedShaRaw } = await this.git(['rev-parse', 'HEAD'], this.worktreePath);
+            const mergedSha = mergedShaRaw.trim();
+            await this.git(['update-ref', targetRef, mergedSha], this.projectPath);
+        }
+        finally {
+            // Restore worktree to the session branch even if merge failed.
+            await this.git(['checkout', this.branch], this.worktreePath).catch(() => { });
+        }
+    }
+    async teardown() {
+        if (this.tornDown)
+            return;
+        // Flush pending commits before marking as torn down
+        await this.commitQueue;
+        this.tornDown = true;
+        if (this.worktreePath && this.projectPath) {
+            // Write step log to branch
+            await this.writeStepLog();
+            // Remove the worktree
+            try {
+                await this.git(['worktree', 'remove', this.worktreePath, '--force'], this.projectPath);
+            }
+            catch {
+                // If worktree removal fails (e.g., already removed), just clean up
+                await fs.rm(this.worktreePath, { recursive: true, force: true });
+                await this.git(['worktree', 'prune'], this.projectPath).catch(() => { });
+            }
+        }
+    }
+    async getDiff(sha) {
+        this.ensureWorktree();
+        try {
+            const { stdout } = await this.git(['diff', `${sha}~1..${sha}`], this.worktreePath);
+            return stdout;
+        }
+        catch {
+            // First commit in worktree has no parent — show all changes
+            const { stdout } = await this.git(['show', '--format=', sha], this.worktreePath);
+            return stdout;
+        }
+    }
+    async getStepDiffs() {
+        const committed = this._steps.filter((step) => !!step.sha);
+        return Promise.all(committed.map(async (step) => ({
+            step: step.step,
+            sha: step.sha,
+            diff: await this.getDiff(step.sha),
+        })));
+    }
+    async getSummaryDiff() {
+        this.ensureWorktree();
+        const stepsWithSha = this._steps.filter((s) => s.sha);
+        if (stepsWithSha.length === 0)
+            return '';
+        const firstSha = stepsWithSha[0].sha;
+        const lastSha = stepsWithSha[stepsWithSha.length - 1].sha;
+        if (firstSha === lastSha) {
+            return this.getDiff(firstSha);
+        }
+        try {
+            const { stdout } = await this.git(['diff', `${firstSha}~1..${lastSha}`], this.worktreePath);
+            return stdout;
+        }
+        catch {
+            const { stdout } = await this.git(['diff', `${firstSha}..${lastSha}`], this.worktreePath);
+            return stdout;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    shouldCommit(toolName) {
+        return this.config.commitOn.includes(toolName);
+    }
+    enqueueCommit(step) {
+        if (this.commitCount >= this.config.maxCommitsPerSession)
+            return;
+        this.commitQueue = this.commitQueue
+            .then(() => this.doCommit(step))
+            .catch((err) => {
+            log.warn({ err, step: step.step, sessionId: this._sessionId }, 'Git commit failed');
+        });
+    }
+    async doCommit(step) {
+        if (this.tornDown || !this.worktreePath)
+            return;
+        // Check if there are any changes
+        const { stdout: status } = await this.git(['status', '--porcelain'], this.worktreePath);
+        if (!status.trim())
+            return; // Nothing to commit
+        // Check we're still on our branch
+        const { stdout: currentBranch } = await this.git(['branch', '--show-current'], this.worktreePath);
+        if (currentBranch.trim() !== this.branch)
+            return; // Agent switched branches
+        // Stage all changes, respecting ignore patterns
+        const addArgs = ['add', '-A'];
+        for (const pattern of this.config.ignore) {
+            addArgs.push(`:(exclude)${pattern}`);
+        }
+        await this.git(addArgs, this.worktreePath);
+        // Check if staging resulted in any changes
+        const { stdout: staged } = await this.git(['diff', '--cached', '--name-only'], this.worktreePath);
+        if (!staged.trim())
+            return; // All changes were ignored
+        // Commit
+        const message = `[viewport] Step ${step.step}: ${step.description}`;
+        // We skip local git hooks because daemon-generated commits must be non-interactive and deterministic.
+        // Operators should enforce secret scanning via centralized CI/push protection.
+        await this.git(['commit', '-m', message, '--author', this.config.commitAuthor, '--no-verify'], this.worktreePath);
+        // Get the commit SHA
+        const { stdout: sha } = await this.git(['rev-parse', 'HEAD'], this.worktreePath);
+        step.sha = sha.trim();
+        this.commitCount++;
+        metrics.increment('git.commits');
+        this.onStepCommitted?.(step);
+    }
+    describeStep(msg) {
+        switch (msg.type) {
+            case 'tool_call':
+                return `${msg.toolName}: ${msg.title}`;
+            case 'tool_call_update':
+                return `${msg.toolName ?? 'tool'} ${msg.status}${msg.title ? ': ' + msg.title : ''}`;
+            case 'user_message':
+                return `User: ${msg.text.slice(0, 80)}`;
+            case 'agent_message':
+                return `Agent: ${msg.text.slice(0, 80)}`;
+            case 'token_usage':
+                return `Token usage: ${msg.inputTokens + msg.outputTokens} tokens`;
+            default:
+                return msg.type;
+        }
+    }
+    async writeStepLog() {
+        if (!this.worktreePath)
+            return;
+        const logPath = path.join(this.worktreePath, '.viewport-session.jsonl');
+        const lines = this._steps.map((s) => JSON.stringify(s)).join('\n') + '\n';
+        try {
+            await fs.writeFile(logPath, lines, 'utf-8');
+            await this.git(['add', '.viewport-session.jsonl'], this.worktreePath);
+            await this.git([
+                'commit',
+                '-m',
+                `[viewport] Session log: ${this._steps.length} steps`,
+                '--author',
+                this.config.commitAuthor,
+                // Keep session-log commits non-interactive for the same reason as step commits.
+                '--no-verify',
+            ], this.worktreePath);
+        }
+        catch {
+            // Non-fatal — session log is nice-to-have
+        }
+    }
+    ensureWorktree() {
+        if (!this.worktreePath) {
+            throw new Error('GitTracker not set up. Call setup() first.');
+        }
+    }
+    async git(args, cwd) {
+        const { stdout, stderr } = await execGit('git', args, {
+            cwd,
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: GIT_TIMEOUT_MS,
+        });
+        return { stdout, stderr };
+    }
+}
+//# sourceMappingURL=git-tracker.js.map

package/dist/tracking/git-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-tracker.js","sourceRoot":"","sources":["../../src/tracking/git-tracker.ts"],"names":[],"mappings":"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"}

package/dist/tracking/noop-tracker.d.ts

@@ -0,0 +1,27 @@
+/**
+ * NoopTracker — a RunTracker that does nothing.
+ *
+ * Used when git tracking is disabled (config.gitTracker.enabled = false).
+ * The agent runs in-place in the project directory with no worktree,
+ * no commits, no rollback capability.
+ */
+import type { RunTracker } from '../core/interfaces.js';
+import type { SessionMessage, Step } from '../core/types.js';
+export declare class NoopTracker implements RunTracker {
+    readonly steps: ReadonlyArray<Step>;
+    setup(_sessionId: string, projectPath: string): Promise<string>;
+    onMessage(_msg: SessionMessage): void;
+    flushPendingCommits(): Promise<void>;
+    rollback(_toSha: string): Promise<void>;
+    branchRetry(_fromSha: string): Promise<string>;
+    squashMerge(_targetBranch: string, _commitMessage: string): Promise<void>;
+    teardown(): Promise<void>;
+    getDiff(_sha: string): Promise<string>;
+    getStepDiffs(): Promise<Array<{
+        step: number;
+        sha: string;
+        diff: string;
+    }>>;
+    getSummaryDiff(): Promise<string>;
+}
+//# sourceMappingURL=noop-tracker.d.ts.map

package/dist/tracking/noop-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-tracker.d.ts","sourceRoot":"","sources":["../../src/tracking/noop-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7D,qBAAa,WAAY,YAAW,UAAU;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAM;IAEnC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKrE,SAAS,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAI/B,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9C,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItC,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAI3E,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;CAGxC"}

package/dist/tracking/noop-tracker.js

@@ -0,0 +1,42 @@
+/**
+ * NoopTracker — a RunTracker that does nothing.
+ *
+ * Used when git tracking is disabled (config.gitTracker.enabled = false).
+ * The agent runs in-place in the project directory with no worktree,
+ * no commits, no rollback capability.
+ */
+export class NoopTracker {
+    steps = [];
+    async setup(_sessionId, projectPath) {
+        // No worktree — run directly in the project directory
+        return projectPath;
+    }
+    onMessage(_msg) {
+        // No tracking
+    }
+    async flushPendingCommits() {
+        // Nothing to flush
+    }
+    async rollback(_toSha) {
+        throw new Error('Rollback is not available without git tracking enabled.');
+    }
+    async branchRetry(_fromSha) {
+        throw new Error('Branch-retry is not available without git tracking enabled.');
+    }
+    async squashMerge(_targetBranch, _commitMessage) {
+        throw new Error('Squash-merge is not available without git tracking enabled.');
+    }
+    async teardown() {
+        // Nothing to clean up
+    }
+    async getDiff(_sha) {
+        return '';
+    }
+    async getStepDiffs() {
+        return [];
+    }
+    async getSummaryDiff() {
+        return '';
+    }
+}
+//# sourceMappingURL=noop-tracker.js.map

package/dist/tracking/noop-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-tracker.js","sourceRoot":"","sources":["../../src/tracking/noop-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,OAAO,WAAW;IACb,KAAK,GAAwB,EAAE,CAAC;IAEzC,KAAK,CAAC,KAAK,CAAC,UAAkB,EAAE,WAAmB;QACjD,sDAAsD;QACtD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,SAAS,CAAC,IAAoB;QAC5B,cAAc;IAChB,CAAC;IAED,KAAK,CAAC,mBAAmB;QACvB,mBAAmB;IACrB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc;QAC3B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,QAAgB;QAChC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,aAAqB,EAAE,cAAsB;QAC7D,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,sBAAsB;IACxB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;CACF"}

package/docs/configuration.md

@@ -0,0 +1,75 @@
+# Viewport Daemon Configuration
+
+## Precedence
+
+Daemon runtime settings resolve in this order (later wins):
+
+1. Built-in defaults
+2. `~/.viewport/config.json` (`daemon.*`)
+3. Environment variables (`VPD_*` / `VIEWPORT_*`)
+4. CLI flags
+
+Session config resolution is separate:
+
+1. Framework built-ins
+2. Agent defaults
+3. Global defaults (`defaults`)
+4. Directory overrides (`directories.<id>.config`)
+5. Session launch overrides
+
+## Runtime keys
+
+`config.json`:
+
+```json
+{
+  "daemon": {
+    "listen": "127.0.0.1:7070",
+    "profile": "local",
+    "allowedHosts": ["localhost"],
+    "allowedOrigins": ["localhost"],
+    "authEnabled": false,
+    "logFile": "~/.viewport/daemon.log",
+    "relay": {
+      "enabled": false,
+      "endpoint": "wss://relay.example.test",
+      "publicEndpoint": "wss://relay.example.test"
+    }
+  }
+}
+```
+
+## Environment variables
+
+- `VPD_LISTEN` / `VIEWPORT_LISTEN`
+- `VPD_PROFILE` / `VIEWPORT_PROFILE`
+- `VPD_ALLOWED_HOSTS` / `VIEWPORT_ALLOWED_HOSTS`
+- `VPD_ALLOWED_ORIGINS` / `VIEWPORT_ALLOWED_ORIGINS`
+- `VPD_AUTH` / `VIEWPORT_AUTH`
+- `VPD_LOG_FILE` / `VIEWPORT_LOG_FILE`
+- `VPD_RELAY_ENABLED` / `VIEWPORT_RELAY_ENABLED`
+- `VPD_RELAY_ENDPOINT` / `VIEWPORT_RELAY_ENDPOINT`
+- `VIEWPORT_HTTP_LOG_LEVEL`
+- `VIEWPORT_MAX_WS_CLIENTS`
+
+## CLI flags
+
+- `--listen`
+- `--profile`
+- `--allowed-hosts`
+- `--allowed-origins`
+- `--auth`
+- `--log-file`
+- `--relay-endpoint`
+- `--no-relay`
+
+## Notes for relay phase
+
+Current daemon config already carries relay keys and security profile semantics.
+Relay transport, cryptographic peer identity, and remote identity binding are intentionally deferred to the relay phase.
+
+## Validation guarantees
+
+- `~/.viewport/config.json` is schema-validated with Zod.
+- Malformed JSON or schema-invalid values fail fast with actionable errors.
+- Unknown keys are rejected to prevent silent misconfiguration drift.

package/docs/developer-workflows.md

@@ -0,0 +1,107 @@
+# Developer Workflows
+
+## Install and run locally
+
+1. Tarball-based local install (recommended):
+
+```bash
+./scripts/install-dev.sh --yes --no-service --no-prereqs --no-hooks
+```
+
+2. `npm link` local install (use only when you specifically need symlink behavior):
+
+```bash
+./scripts/install-dev.sh --link --yes --no-service --no-prereqs --no-hooks
+```
+
+## Uninstall / reinstall locally
+
+1. Remove global package and user service:
+
+```bash
+npm run dev:uninstall
+```
+
+2. Remove package + service + daemon home/state:
+
+```bash
+npm run dev:uninstall:all
+```
+
+3. Reinstall from current local source:
+
+```bash
+npm run dev:reinstall
+```
+
+Note on macOS background item naming:
+The Login Items UI may show `Node.js Foundation` for the daemon service because launchd runs the Node runtime binary. That name comes from the executable signature, not the launchd label (`ai.viewport.daemon`).
+If you ever see `sh` there, your service was installed from an older shell-wrapper plist; run `vpd service uninstall && vpd service install` to refresh it.
+
+## Why tarball install exists
+
+`npm pack` builds the exact package artifact that npm would publish (`@viewportai/daemon-<version>.tgz`).
+Installing from that tarball verifies all of these in one path:
+
+1. `files`/packaging manifest is correct.
+2. `bin` (`vpd`) resolves correctly after install.
+3. Runtime dependencies are present in the packaged artifact.
+4. Real install behavior matches production npm installs.
+
+That makes tarball install a stronger release-confidence check than `npm link`, which can hide packaging mistakes by running directly from the source tree.
+
+## Verification scripts
+
+1. Repository quality gate:
+
+```bash
+npm run verify:repo
+```
+
+2. Environment verification (isolated runtime):
+
+```bash
+npm run verify:env
+```
+
+3. Environment verification + OS service checks:
+
+```bash
+npm run verify:env:service
+```
+
+4. Package/install verification from isolated npm prefix:
+
+```bash
+npm run verify:install
+```
+
+Note: this command requires internet access to resolve package runtime dependencies.
+
+5. Combined verification with optional flags:
+
+```bash
+./scripts/verify.sh --fullstack --env --service
+```
+
+## Unified test command modes
+
+```bash
+npm run test
+npm run test --verify
+npm run test --e2e
+npm run test --fullstack
+npm run test --env
+npm run test --service
+```
+
+## Script surface (canonical)
+
+Use only these shell entrypoints:
+
+1. `scripts/install.sh`
+2. `scripts/install-dev.sh`
+3. `scripts/test.sh`
+4. `scripts/test-env.sh`
+5. `scripts/install-verify.sh`
+6. `scripts/verify.sh`