byterover-cli 1.0.3 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # ByteRover CLI
 
-Command-line interface for ByteRover, featuring an interactive REPL with a modern terminal UI for managing your project's context tree and memory storage.
+Command-line interface for ByteRover, featuring an interactive REPL with a modern React/Ink terminal UI for managing your project's context tree and knowledge storage. Seamlessly integrate with AI coding agents like Claude Code, Cursor, Windsurf, and GitHub Copilot.
 
 [![Version](https://img.shields.io/npm/v/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
 [![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
@@ -15,6 +15,7 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
 * [Slash Commands Reference](#slash-commands-reference)
 * [Authentication](#authentication)
 * [Configuration](#configuration)
+* [Troubleshooting](#troubleshooting)
 * [Getting Help](#getting-help)
 
 ## Installation
@@ -90,6 +91,16 @@ brv
 
 Running `brv` without arguments starts the interactive REPL. The REPL requires an interactive terminal (TTY).
 
+### TUI Features
+
+The terminal UI includes:
+
+- **Tab Navigation**: Switch between Chat and Activity views using `Tab`
+- **Command Completion**: Type `/` to see available commands with auto-completion
+- **Activity Log**: Real-time task status and execution progress
+- **Streaming Output**: Live responses from AI-powered operations
+- **File References**: Type `@` in curate mode to browse and attach files
+
 ### Using Commands
 
 In the REPL, use slash commands (commands prefixed with `/`) to interact with ByteRover:
@@ -104,24 +115,33 @@ Commands support tab completion for quick navigation.
 
 ## What is Context Tree?
 
-The **Context Tree** is ByteRover's structured memory system that helps you and your coding agents organize, store, and retrieve project knowledge efficiently.
+The **Context Tree** is ByteRover's structured knowledge system that helps you and your AI coding agents organize, store, and retrieve project context efficiently.
 
 ### Why Use Context Tree?
 
 - **Organized Knowledge**: Structure your project knowledge by domain and topic
 - **Easy Retrieval**: Find relevant context quickly when you need it
 - **Persistent Memory**: Maintain project-specific knowledge across sessions
-- **Agent-Friendly**: Works seamlessly with coding agents like Claude Code, Cursor, and others
-- **Version Control**: Push and sync your context to ByteRover's cloud storage
+- **Agent-Friendly**: Works seamlessly with AI coding agents like Claude Code, Cursor, Windsurf, and GitHub Copilot
+- **Cloud Sync**: Push and sync your context tree to ByteRover's cloud storage for backup and team collaboration
+- **Dynamic Domains**: Automatically creates new domains as your knowledge grows
 
 ### How It Works
 
 The context tree organizes knowledge into:
-- **Domains**: High-level categories (e.g., Architecture, API, Frontend)
+- **Domains**: High-level categories (e.g., Architecture, API, Frontend) — created automatically or manually
 - **Topics**: Specific subjects within domains (e.g., Authentication, Components)
 - **Context Files**: Markdown files containing your actual knowledge
 
-For comprehensive instructions for coding agents, use `/gen-rules` to generate rule files.
+### Integrating with Coding Agents
+
+Use `/gen-rules` to generate rule instruction files that help your AI coding agents understand and work with ByteRover:
+
+```
+/gen-rules
+```
+
+This creates agent-specific rule files (e.g., `CLAUDE.md`, `.cursorrules`) that instruct the agent how to read from and contribute to your context tree.
 
 ## Slash Commands Reference
 
@@ -150,8 +170,8 @@ For comprehensive instructions for coding agents, use `/gen-rules` to generate r
 
 | Command | Description |
 |---------|-------------|
-| `/push [-b branch] [-y]` | Push context tree to ByteRover memory storage |
-| `/pull [-b branch]` | Pull context tree from ByteRover memory storage |
+| `/push [-b branch] [-y]` | Push context tree to ByteRover cloud storage |
+| `/pull [-b branch]` | Pull context tree from ByteRover cloud storage |
 
 **Options:**
 - `-b, --branch <name>`: ByteRover branch name (default: `main`)
@@ -182,7 +202,7 @@ For comprehensive instructions for coding agents, use `/gen-rules` to generate r
 
 | Command | Description |
 |---------|-------------|
-| `/gen-rules` | Generate rule instructions for coding agents |
+| `/gen-rules` | Generate rule files for AI coding agents (Claude Code, Cursor, etc.) |
 | `/clear [-y] [directory]` | Reset context tree to default domains |
 
 **Clear options:**
@@ -232,6 +252,16 @@ When you run `/init`, a configuration file is created at `.brv/config.json` in y
 - **User information**: Your user ID and email
 - **Project settings**: Project-specific configuration
 
+### Global Configuration
+
+User-level configuration is stored at `~/.config/brv/`:
+
+```
+~/.config/brv/
+├── config.json    # Global settings and device ID
+└── logs/          # Session logs for debugging
+```
+
 ### Context Tree Structure
 
 The context tree is stored in `.brv/context-tree/`:
@@ -255,7 +285,29 @@ The context tree is stored in `.brv/context-tree/`:
         └── context.md
 ```
 
-**Note**: When you run `/push`, your context tree is uploaded to ByteRover's memory storage for version control and team collaboration.
+**Note**: When you run `/push`, your context tree is uploaded to ByteRover's cloud storage for version control and team collaboration.
+
+## Troubleshooting
+
+### Session Logs
+
+If you encounter issues, session logs are stored at `~/.config/brv/logs/`. Each session creates a timestamped log file (e.g., `brv-2024-01-15T10-30-00.log`) that can help diagnose problems.
+
+### Instance Lock
+
+ByteRover CLI ensures only one instance runs per project folder. If you see an "instance already running" message:
+
+1. Check for another terminal with `brv` running in the same directory
+2. If no other instance is visible, the lock file may be stale — it will auto-release on the next start
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "REPL requires an interactive terminal" | Run `brv` directly in a terminal, not through piped commands |
+| Authentication expires frequently | Run `/login` to refresh your session |
+| Context tree not syncing | Check `/status` for sync status, then try `/push` or `/pull` |
+| Rule files not generated | Ensure you're in a project directory with `.brv/` initialized |
 
 ## Getting Help
 

package/dist/commands/curate.js

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { isDevelopment } from '../config/environment.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { CurateUseCase } from '../infra/usecase/curate-use-case.js';
@@ -49,7 +49,7 @@ Bad examples:
             : {}),
     };
     createUseCase() {
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const terminal = new OclifTerminal(this);
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });

package/dist/commands/main.js

@@ -4,7 +4,7 @@ import { getProcessManager } from '../infra/process/index.js';
 import { startRepl } from '../infra/repl/repl-startup.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
 import { FileOnboardingPreferenceStore } from '../infra/storage/file-onboarding-preference-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { initSessionLog } from '../utils/process-logger.js';
 /**
@@ -33,7 +33,7 @@ export default class Main extends Command {
         // Start Transport and Agent processes (v0.5.0 architecture)
         const processManager = getProcessManager();
         await processManager.start();
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         const onboardingPreferenceStore = new FileOnboardingPreferenceStore();

package/dist/commands/query.js

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { isDevelopment } from '../config/environment.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { QueryUseCase } from '../infra/usecase/query-use-case.js';
@@ -40,7 +40,7 @@ Bad:
     };
     static strict = false;
     createUseCase() {
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         return new QueryUseCase({

package/dist/commands/status.js

@@ -3,7 +3,7 @@ import { ProjectConfigStore } from '../infra/config/file-config-store.js';
 import { FileContextTreeService } from '../infra/context-tree/file-context-tree-service.js';
 import { FileContextTreeSnapshotService } from '../infra/context-tree/file-context-tree-snapshot-service.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { createTokenStore } from '../infra/storage/token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
 import { StatusUseCase } from '../infra/usecase/status-use-case.js';
@@ -29,7 +29,7 @@ export default class Status extends Command {
         }),
     };
     createUseCase() {
-        const tokenStore = new KeychainTokenStore();
+        const tokenStore = createTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         const contextTreeSnapshotService = new FileContextTreeSnapshotService();

package/dist/config/context-tree-domains.d.ts

@@ -1,17 +1,29 @@
 /**
  * Domain configurations for the context tree structure.
  * Each domain represents a specific area of knowledge in the project.
+ *
+ * @deprecated Domains are now created dynamically based on content semantics.
+ * This file is kept for backward compatibility only.
  */
 export interface DomainConfig {
     description: string;
     name: string;
 }
 /**
- * Predefined domains that will be scaffolded during project initialization.
+ * Example domain names for reference only.
+ * Domains are now created dynamically by the agent based on content.
+ *
+ * @deprecated Domains are created dynamically. These are kept as examples only.
+ */
+export declare const EXAMPLE_DOMAIN_NAMES: readonly ["authentication", "api_design", "data_models", "error_handling", "ui_components", "testing_patterns", "configuration", "logging", "security", "performance"];
+/**
+ * @deprecated Domains are now created dynamically based on content semantics.
+ * The agent will create domain names that are semantically meaningful for the curated content.
+ * This constant is kept for backward compatibility but is no longer used.
  */
 export declare const DEFAULT_CONTEXT_TREE_DOMAINS: DomainConfig[];
 /**
  * Alias for backward compatibility.
- * @deprecated Use DEFAULT_CONTEXT_TREE_DOMAINS instead
+ * @deprecated Domains are created dynamically. This constant is no longer used.
  */
 export declare const CONTEXT_TREE_DOMAINS: DomainConfig[];

package/dist/config/context-tree-domains.js

@@ -1,34 +1,29 @@
 /**
- * Predefined domains that will be scaffolded during project initialization.
+ * Example domain names for reference only.
+ * Domains are now created dynamically by the agent based on content.
+ *
+ * @deprecated Domains are created dynamically. These are kept as examples only.
  */
-export const DEFAULT_CONTEXT_TREE_DOMAINS = [
-    {
-        description: 'Ensure all code follows style guidelines and quality standards',
-        name: 'code_style',
-    },
-    {
-        description: 'UI libraries, themes, and design guidelines',
-        name: 'design',
-    },
-    {
-        description: 'Project structure, components, and related context',
-        name: 'structure',
-    },
-    {
-        description: 'Security and compliance information',
-        name: 'compliance',
-    },
-    {
-        description: 'Testing implementation context',
-        name: 'testing',
-    },
-    {
-        description: 'Bug fixing logic and procedures',
-        name: 'bug_fixes',
-    },
+export const EXAMPLE_DOMAIN_NAMES = [
+    'authentication',
+    'api_design',
+    'data_models',
+    'error_handling',
+    'ui_components',
+    'testing_patterns',
+    'configuration',
+    'logging',
+    'security',
+    'performance',
 ];
+/**
+ * @deprecated Domains are now created dynamically based on content semantics.
+ * The agent will create domain names that are semantically meaningful for the curated content.
+ * This constant is kept for backward compatibility but is no longer used.
+ */
+export const DEFAULT_CONTEXT_TREE_DOMAINS = [];
 /**
  * Alias for backward compatibility.
- * @deprecated Use DEFAULT_CONTEXT_TREE_DOMAINS instead
+ * @deprecated Domains are created dynamically. This constant is no longer used.
  */
 export const CONTEXT_TREE_DOMAINS = DEFAULT_CONTEXT_TREE_DOMAINS;

package/dist/constants.d.ts

@@ -6,6 +6,7 @@ export declare const BRV_CONFIG_VERSION = "0.0.1";
 export declare const GLOBAL_CONFIG_DIR = "brv";
 export declare const GLOBAL_CONFIG_FILE = "config.json";
 export declare const GLOBAL_CONFIG_VERSION = "0.0.1";
+export declare const GLOBAL_DATA_DIR = "brv";
 export declare const ACE_DIR = "ace";
 export declare const PROJECT = "byterover";
 export declare const CONTEXT_TREE_DIR = "context-tree";

package/dist/constants.js

@@ -7,6 +7,9 @@ export const BRV_CONFIG_VERSION = '0.0.1';
 export const GLOBAL_CONFIG_DIR = 'brv';
 export const GLOBAL_CONFIG_FILE = 'config.json';
 export const GLOBAL_CONFIG_VERSION = '0.0.1';
+// Global data directory name (for XDG_DATA_HOME - secrets, credentials, cache)
+// Same value as GLOBAL_CONFIG_DIR but different semantic purpose
+export const GLOBAL_DATA_DIR = 'brv';
 // ACE directory structure constants
 export const ACE_DIR = 'ace';
 export const PROJECT = 'byterover';

package/dist/core/domain/cipher/file-system/types.d.ts

@@ -146,6 +146,8 @@ export interface FileContent {
     totalLines: number;
     /** Whether content was truncated due to size/line limits */
     truncated: boolean;
+    /** Number of lines that were truncated due to excessive length */
+    truncatedLineCount?: number;
 }
 /**
  * Result of a file write operation.

package/dist/core/domain/entities/auth-token.js

@@ -24,9 +24,12 @@ export class AuthToken {
      * @returns An instance of AuthToken, or undefined if required fields are missing
      */
     static fromJson(json) {
-        // Validate that new required fields exist (for backward compatibility with old tokens)
-        if (!json.userId || !json.userEmail) {
-            return undefined;
+        // Validate ALL required fields exist (prevents corrupted/incomplete tokens from being loaded)
+        const requiredFields = ['accessToken', 'expiresAt', 'refreshToken', 'sessionKey', 'userEmail', 'userId'];
+        for (const field of requiredFields) {
+            if (!json[field]) {
+                return undefined;
+            }
         }
         return new AuthToken({
             accessToken: json.accessToken,

package/dist/core/domain/entities/event.d.ts

@@ -1,7 +1,7 @@
 /**
  * Array of all supported Events.
  */
-export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
+export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "auth:token_invalid", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
 export type EventName = (typeof EVENT_VALUES)[number];
 export interface PropertyDict {
     [key: string]: any;

package/dist/core/domain/entities/event.js

@@ -5,6 +5,7 @@ export const EVENT_VALUES = [
     'repl',
     'auth:sign_in',
     'auth:signed_out',
+    'auth:token_invalid',
     'space:init',
     'space:changed',
     'rule:generate',
@@ -18,5 +19,5 @@ export const EVENT_VALUES = [
     'onboarding:query_completed',
     'onboarding:skipped',
     'onboarding:completed',
-    'init'
+    'init',
 ];

package/dist/core/domain/knowledge/relation-parser.d.ts

@@ -71,11 +71,26 @@ export declare function resolveRelationPath(basePath: string, relation: string):
  * ```
  */
 export declare function formatRelation(domain: string, topic: string, subtopic?: string): string;
+/**
+ * Normalize a relation path by removing the @ prefix.
+ *
+ * @param relation - Relation path to normalize
+ * @returns Normalized relation path
+ *
+ * @example
+ * ```ts
+ * normalizeRelation('code_style/error-handling') // 'code_style/error-handling'
+ * normalizeRelation('@code_style/error-handling') // 'code_style/error-handling'
+ * normalizeRelation('code_style/error-handling/title.md') // 'code_style/error-handling/title.md'
+ * normalizeRelation('@@@code_style/error-handling/title.md') // 'code_style/error-handling/title.md'
+ * ```
+ */
+export declare function normalizeRelation(relation: string): string;
 /**
  * Generate the Relations section for context.md.
  * Returns empty string if no relations provided.
  *
- * @param relations - Array of relation paths (without @ prefix)
+ * @param relations - Array of relation paths (with or without @ prefix)
  * @returns Markdown formatted Relations section or empty string
  *
  * @example

package/dist/core/domain/knowledge/relation-parser.js

@@ -104,11 +104,28 @@ export function formatRelation(domain, topic, subtopic) {
         ? `@${domain}/${topic}/${subtopic}`
         : `@${domain}/${topic}`;
 }
+/**
+ * Normalize a relation path by removing the @ prefix.
+ *
+ * @param relation - Relation path to normalize
+ * @returns Normalized relation path
+ *
+ * @example
+ * ```ts
+ * normalizeRelation('code_style/error-handling') // 'code_style/error-handling'
+ * normalizeRelation('@code_style/error-handling') // 'code_style/error-handling'
+ * normalizeRelation('code_style/error-handling/title.md') // 'code_style/error-handling/title.md'
+ * normalizeRelation('@@@code_style/error-handling/title.md') // 'code_style/error-handling/title.md'
+ * ```
+ */
+export function normalizeRelation(relation) {
+    return relation.replace(/^@+/, '');
+}
 /**
  * Generate the Relations section for context.md.
  * Returns empty string if no relations provided.
  *
- * @param relations - Array of relation paths (without @ prefix)
+ * @param relations - Array of relation paths (with or without @ prefix)
  * @returns Markdown formatted Relations section or empty string
  *
  * @example
@@ -125,7 +142,7 @@ export function generateRelationsSection(relations) {
         return '';
     }
     const formattedRelations = relations
-        .map(rel => `@${rel}`)
+        .map(rel => `@${normalizeRelation(rel)}`)
         .join('\n');
     return `\n## Relations\n${formattedRelations}\n`;
 }

package/dist/core/domain/transport/schemas.d.ts

@@ -451,6 +451,8 @@ export declare const TransportSessionEventNames: {
 export declare const TaskExecuteSchema: z.ZodObject<{
     /** Client ID that created the task (for response routing) */
     clientId: z.ZodString;
+    /** Client's working directory for file validation */
+    clientCwd: z.ZodOptional<z.ZodString>;
     /** Task content/prompt */
     content: z.ZodString;
     /** Optional file paths for curate --files */
@@ -464,12 +466,14 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     content: string;
     clientId: string;
     taskId: string;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }, {
     type: "curate" | "query";
     content: string;
     clientId: string;
     taskId: string;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }>;
 /**
@@ -606,6 +610,8 @@ export declare const TaskAckSchema: z.ZodObject<{
  * Sent to broadcast-room for TUI monitoring
  */
 export declare const TaskCreatedSchema: z.ZodObject<{
+    /** Client's working directory for file validation */
+    clientCwd: z.ZodOptional<z.ZodString>;
     /** Task content/prompt */
     content: z.ZodString;
     /** Optional file paths for curate --files */
@@ -618,19 +624,23 @@ export declare const TaskCreatedSchema: z.ZodObject<{
     type: "curate" | "query";
     content: string;
     taskId: string;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }, {
     type: "curate" | "query";
     content: string;
     taskId: string;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }>;
 /**
  * task:started - Agent begins processing the task
  * Direct send: {taskId} only
- * Broadcast: {taskId, content, type, files?}
+ * Broadcast: {taskId, content, type, files?, clientCwd?}
  */
 export declare const TaskStartedEventSchema: z.ZodObject<{
+    /** Client's working directory for file validation */
+    clientCwd: z.ZodOptional<z.ZodString>;
     /** Task content/prompt */
     content: z.ZodOptional<z.ZodString>;
     /** Optional file paths for curate --files */
@@ -643,11 +653,13 @@ export declare const TaskStartedEventSchema: z.ZodObject<{
     taskId: string;
     type?: string | undefined;
     content?: string | undefined;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }, {
     taskId: string;
     type?: string | undefined;
     content?: string | undefined;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }>;
 /**
@@ -854,6 +866,8 @@ export declare const TaskTypeSchema: z.ZodEnum<["curate", "query"]>;
  * Request to create a new task
  */
 export declare const TaskCreateRequestSchema: z.ZodObject<{
+    /** Client's working directory for file validation */
+    clientCwd: z.ZodOptional<z.ZodString>;
     /** Task content/prompt */
     content: z.ZodString;
     /** Optional file paths for curate --files (max 5) */
@@ -866,11 +880,13 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     type: "curate" | "query";
     content: string;
     taskId: string;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }, {
     type: "curate" | "query";
     content: string;
     taskId: string;
+    clientCwd?: string | undefined;
     files?: string[] | undefined;
 }>;
 /**

package/dist/core/domain/transport/schemas.js

@@ -274,6 +274,8 @@ export const TransportSessionEventNames = {
 export const TaskExecuteSchema = z.object({
     /** Client ID that created the task (for response routing) */
     clientId: z.string(),
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
     /** Task content/prompt */
     content: z.string(),
     /** Optional file paths for curate --files */
@@ -326,6 +328,8 @@ export const TaskAckSchema = z.object({
  * Sent to broadcast-room for TUI monitoring
  */
 export const TaskCreatedSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
     /** Task content/prompt */
     content: z.string(),
     /** Optional file paths for curate --files */
@@ -338,9 +342,11 @@ export const TaskCreatedSchema = z.object({
 /**
  * task:started - Agent begins processing the task
  * Direct send: {taskId} only
- * Broadcast: {taskId, content, type, files?}
+ * Broadcast: {taskId, content, type, files?, clientCwd?}
  */
 export const TaskStartedEventSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
     /** Task content/prompt */
     content: z.string().optional(),
     /** Optional file paths for curate --files */
@@ -431,6 +437,8 @@ export const TaskTypeSchema = z.enum(['curate', 'query']);
  * Request to create a new task
  */
 export const TaskCreateRequestSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
     /** Task content/prompt */
     content: z.string().min(1),
     /** Optional file paths for curate --files (max 5) */

package/dist/core/interfaces/cipher/i-blob-storage.d.ts

@@ -11,6 +11,12 @@ export interface IBlobStorage {
      * @throws If clearing fails
      */
     clear(): Promise<void>;
+    /**
+     * Close the storage connection and release resources.
+     * Should be called when storage is no longer needed.
+     * Safe to call multiple times (idempotent).
+     */
+    close(): void;
     /**
      * Delete a blob by its key
      *

package/dist/core/interfaces/cipher/index.d.ts

@@ -5,7 +5,6 @@
  */
 export type { BlobMetadata, StoredBlob } from '../../domain/cipher/blob/types.js';
 export * from './cipher-services.js';
-export type { IAgentStorage } from './i-agent-storage.js';
 export type { IBlobStorage } from './i-blob-storage.js';
 export type { IChatSession } from './i-chat-session.js';
 export type { ICipherAgent } from './i-cipher-agent.js';

package/dist/core/interfaces/executor/i-curate-executor.d.ts

@@ -6,6 +6,8 @@ import type { ICipherAgent } from '../cipher/i-cipher-agent.js';
 export interface CurateExecuteOptions {
     /** Context content to curate */
     content: string;
+    /** Client's working directory for file validation (defaults to process.cwd() if not provided) */
+    clientCwd?: string;
     /** Optional file paths for --files flag */
     files?: string[];
     /** Task ID for event routing (required for concurrent task isolation) */

package/dist/infra/cipher/agent/cipher-agent.js

@@ -122,6 +122,10 @@ export class CipherAgent extends BaseAgent {
         if (this.stateManager) {
             this.stateManager.reset();
         }
+        // Close SQLite databases to release file handles and ensure clean shutdown
+        if (this.services?.blobStorage) {
+            this.services.blobStorage.close();
+        }
     }
     /**
      * Create a new session.

package/dist/infra/cipher/file-system/file-system-service.d.ts

@@ -6,6 +6,10 @@ import type { IFileSystem } from '../../../core/interfaces/cipher/i-file-system.
  * path validation, size limits, and allow/block list enforcement.
  */
 export declare class FileSystemService implements IFileSystem {
+    /**
+     * Maximum line length before truncation (2000 characters).
+     */
+    private static readonly MAX_LINE_LENGTH;
     private readonly config;
     private initialized;
     private readonly pathValidator;

package/dist/infra/cipher/file-system/file-system-service.js

@@ -118,6 +118,10 @@ const LIST_DIRECTORY_LIMIT = 100;
  * path validation, size limits, and allow/block list enforcement.
  */
 export class FileSystemService {
+    /**
+     * Maximum line length before truncation (2000 characters).
+     */
+    static MAX_LINE_LENGTH = 2000;
     config;
     initialized = false;
     pathValidator;
@@ -505,6 +509,7 @@ export class FileSystemService {
                 size: stats.size,
                 totalLines,
                 truncated,
+                truncatedLineCount: truncatedLines.length,
             };
         }
         catch (error) {