brainclaw 1.5.4 → 1.6.0

package/dist/core/schema.js

@@ -232,6 +232,17 @@ export const HandoffSchema = z.object({
      */
     superseded_by: z.string().optional(),
     supersedes: z.string().optional(),
+    /**
+     * pln#365 finalization: opt-in cloud federation. Optional (no default) so
+     * existing on-disk handoffs without the field continue to parse, AND so
+     * an unset value means "stay local" rather than "implicitly shared". To
+     * opt a handoff into cloud push, set `visibility: 'shared'` explicitly
+     * when building it. Session-end push uses literal `visibility === 'shared'`
+     * (cf. session-end.ts:isExplicitlyShared). Risk it mitigates: a session
+     * handoff with `snapshot.diff` carrying secrets would otherwise leak the
+     * moment cloud_sync flips on, by virtue of being created at all.
+     */
+    visibility: MemoryVisibilitySchema.optional(),
 });
 export const PlanStatusSchema = z.enum(['todo', 'in_progress', 'blocked', 'done', 'dropped']);
 export const PlanStepStatusSchema = z.enum(['todo', 'in_progress', 'testing', 'done', 'blocked']);
@@ -243,7 +254,8 @@ export const PlanStepSchema = z.object({
     created_at: z.string(),
     updated_at: z.string(),
 });
-export const PlanTypeSchema = z.enum(['feat', 'fix', 'chore', 'spike', 'doc']).default('feat');
+export const PlanTypeEnumSchema = z.enum(['feat', 'fix', 'chore', 'spike', 'doc']);
+export const PlanTypeSchema = PlanTypeEnumSchema.default('feat');
 export const PlanItemSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
@@ -532,6 +544,13 @@ export const CandidateSchema = z.preprocess(candidatePreprocess, z.object({
     resolved_by: z.string().optional(),
     resolution_reason: z.string().optional(),
     provenance: ProvenancePassthroughSchema,
+    /**
+     * pln#365 finalization: opt-in cloud federation. Mirrors HandoffSchema —
+     * optional (no default) so unset means "stay local" and an agent must
+     * explicitly set `visibility: 'shared'` to opt a candidate into cloud
+     * push. Conservative because candidate.text can carry secrets.
+     */
+    visibility: MemoryVisibilitySchema.optional(),
 }));
 export const ReflectiveMemoryConfigSchema = z.object({
     enabled: z.boolean().default(true),
@@ -598,6 +617,7 @@ export const AssignmentStatusSchema = z.enum([
     'accepted', // Worker acknowledged receipt
     'started', // Worker reports active work begun
     'completed', // Worker reports successful completion
+    'cancelled', // Supervisor/admin aborted the assignment explicitly
     'failed', // Worker reports failure
     'blocked', // Worker reports external blocker
     'timed_out', // Sweeper detected no heartbeat within TTL
@@ -642,6 +662,7 @@ export const AssignmentSchema = z.object({
     accepted_at: z.string().optional(),
     started_at: z.string().optional(),
     completed_at: z.string().optional(),
+    cancelled_at: z.string().optional(),
     failed_at: z.string().optional(),
     blocked_at: z.string().optional(),
     timed_out_at: z.string().optional(),
@@ -754,6 +775,7 @@ export const ActionRequiredSchema = z.object({
     tags: TagsWithDefaultSchema,
 });
 // --- Runtime notes schemas ---
+export const RuntimeNoteTypeSchema = z.enum(['observation', 'session_start', 'session_end']);
 export const RuntimeNoteSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     id: z.string(),
@@ -769,7 +791,7 @@ export const RuntimeNoteSchema = z.object({
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
-    note_type: z.enum(['observation', 'session_start', 'session_end']).default('observation'),
+    note_type: RuntimeNoteTypeSchema.default('observation'),
     model: z.string().optional(),
     provenance: ProvenancePassthroughSchema,
 });
@@ -814,6 +836,7 @@ export const RuntimeEventTypeSchema = z.enum([
     'assignment_started',
     'assignment_progress',
     'assignment_completed',
+    'assignment_cancelled',
     'assignment_failed',
     'assignment_blocked',
     'assignment_timed_out',
@@ -934,6 +957,11 @@ export const RemoteSyncSchema = z.object({
     ssh_key_path: z.string().optional(),
     sync_strategy: z.enum(['pull-only', 'push-pull', 'pr-based']).default('push-pull'),
 });
+export const CloudSyncConfigSchema = z.object({
+    enabled: z.boolean().default(false),
+    endpoint: z.string().default('https://app.brainclaw.dev'),
+    api_key: z.string().optional(),
+});
 export const SessionSnapshotSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     session_id: z.string(),
@@ -1229,6 +1257,7 @@ export const ConfigSchema = z.object({
     target_audience: z.enum(['human', 'agent']).optional().default('human'),
     openclaw_bridge: z.boolean().optional().default(false),
     remote_sync: RemoteSyncSchema.optional(),
+    cloud_sync: CloudSyncConfigSchema.optional(),
     telemetry: z.literal(false),
     allow_network: z.literal(false),
     redaction: RedactionConfigSchema,

package/dist/core/state.js

@@ -37,6 +37,68 @@ function loadDirectoryItems(dirPath, schema, documentType) {
     }
     return items;
 }
+const ENTITY_LOAD_CONFIG = {
+    constraint: { subdir: 'constraints', documentType: 'constraint', recursive: false },
+    decision: { subdir: 'decisions', documentType: 'decision', recursive: false },
+    trap: { subdir: 'traps', documentType: 'trap', recursive: false },
+    handoff: { subdir: 'handoffs', documentType: 'handoff', recursive: false },
+    plan: { subdir: 'plans', documentType: 'plan', recursive: false },
+    candidate: { subdir: 'inbox', documentType: 'candidate', recursive: false },
+    claim: { subdir: 'claims', documentType: 'claim', recursive: false },
+    assignment: { subdir: 'assignments', documentType: 'assignment', recursive: false },
+    agent_run: { subdir: 'runs', documentType: 'agent_run', recursive: false },
+    action: { subdir: 'actions', documentType: 'action_required', recursive: false },
+    runtime_note: { subdir: 'runtime', documentType: 'runtime_note', recursive: true },
+};
+function listJsonFiles(dirPath, recursive) {
+    if (!fs.existsSync(dirPath))
+        return [];
+    const files = [];
+    for (const entry of fs.readdirSync(dirPath).sort()) {
+        const fullPath = path.join(dirPath, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            if (recursive)
+                files.push(...listJsonFiles(fullPath, true));
+            continue;
+        }
+        if (entry.endsWith('.json'))
+            files.push(fullPath);
+    }
+    return files;
+}
+function validationErrorsFrom(error) {
+    if (error && typeof error === 'object' && 'issues' in error && Array.isArray(error.issues)) {
+        return (error.issues).map((issue) => {
+            const issuePath = Array.isArray(issue.path) && issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+            return `${issuePath}${issue.message ?? 'validation failed'}`;
+        });
+    }
+    return [error instanceof Error ? error.message : String(error)];
+}
+export function collectLoadValidationWarnings(entity, cwd) {
+    const config = ENTITY_LOAD_CONFIG[entity];
+    if (!config)
+        return [];
+    const effectiveCwd = cwd ?? process.cwd();
+    const dirPath = resolveEntityDir(config.subdir, effectiveCwd, 'read');
+    return listJsonFiles(dirPath, config.recursive).flatMap((filepath) => {
+        try {
+            loadVersionedJsonFile(config.documentType, filepath);
+            return [];
+        }
+        catch (error) {
+            return [{
+                    entity_id: path.basename(filepath, '.json'),
+                    validation_errors: validationErrorsFrom(error),
+                    path: filepath,
+                }];
+        }
+    });
+}
+export function findLoadValidationWarning(entity, id, cwd) {
+    return collectLoadValidationWarnings(entity, cwd).find((warning) => warning.entity_id === id);
+}
 export function loadState(cwd) {
     // Load from entity-aligned directories (with legacy fallback)
     const effectiveCwd = cwd ?? process.cwd();

package/dist/core/store-resolution.js

@@ -91,48 +91,53 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
  *
  * Priority:
  * 1. explicitCwd (--cwd flag)
- * 2. BRAINCLAW_CWD env var → absolute workspace path injected by MCP configs
- * 3. BRAINCLAW_PROJECT env var → resolved by name/path from workspace
- * 4. Session-scoped active project (from .current-session)
+ * 2. BRAINCLAW_CWD env var → workspace anchor injected by MCP configs
+ * 3. BRAINCLAW_PROJECT env var → resolved by name/path from workspace anchor
+ * 4. Session-scoped active project (from .current-session under the anchor)
  * 5. Global active-project.json in workspace root
- * 6. process.cwd()
+ * 6. Workspace anchor or process.cwd()
  */
 export function resolveEffectiveCwd(options = {}) {
+    const baseCwd = path.resolve(options.baseCwd ?? process.cwd());
     // 1. Explicit --cwd flag
     if (options.explicitCwd) {
         return path.resolve(options.explicitCwd);
     }
-    // 2. BRAINCLAW_CWD env var — set by MCP configs to bind to the workspace
-    //    regardless of the IDE's process.cwd() at launch time
+    // 2. BRAINCLAW_CWD env var — set by MCP configs to anchor resolution to the
+    //    workspace regardless of the IDE's process.cwd() at launch time. It is a
+    //    workspace anchor, not the final answer: session/global active project
+    //    state still overrides it.
+    let anchorCwd = baseCwd;
     const envCwd = process.env.BRAINCLAW_CWD?.trim();
-    if (envCwd && fs.existsSync(path.join(path.resolve(envCwd), MEMORY_DIR, 'config.yaml'))) {
-        return path.resolve(envCwd);
+    const hasEnvWorkspace = !!envCwd && fs.existsSync(path.join(path.resolve(envCwd), MEMORY_DIR, 'config.yaml'));
+    if (hasEnvWorkspace) {
+        anchorCwd = path.resolve(envCwd);
     }
     // 3. BRAINCLAW_PROJECT env var
     const envProject = process.env.BRAINCLAW_PROJECT;
     if (envProject) {
-        const resolved = resolveProjectRef(envProject, process.cwd(), options.storeChainOptions);
+        const resolved = resolveProjectRef(envProject, anchorCwd, options.storeChainOptions);
         if (resolved)
             return resolved;
     }
-    // 3. Session-scoped active project (per-agent, no cross-agent interference)
-    const session = loadCurrentSession(process.cwd());
+    // 4. Session-scoped active project (per-agent, no cross-agent interference)
+    const session = loadCurrentSession(anchorCwd);
     if (session?.active_project) {
         const sp = session.active_project;
         if (fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
             return sp.path;
         }
     }
-    // 4. Global active-project.json from workspace root
-    const wsRoot = resolveWorkspaceRoot(process.cwd(), options.storeChainOptions);
+    // 5. Global active-project.json from workspace root
+    const wsRoot = hasEnvWorkspace ? anchorCwd : resolveWorkspaceRoot(anchorCwd, options.storeChainOptions);
     if (wsRoot) {
         const active = loadActiveProject(wsRoot);
         if (active && fs.existsSync(path.join(active.path, MEMORY_DIR, 'config.yaml'))) {
             return active.path;
         }
     }
-    // 5. Default
-    return process.cwd();
+    // 6. Default
+    return anchorCwd;
 }
 /**
  * Find the workspace root (farthest store in the chain, or the one with
@@ -150,9 +155,14 @@ export function resolveWorkspaceRoot(cwd = process.cwd(), options = {}) {
  * Returns undefined when the reference cannot be resolved to a valid brainclaw project.
  */
 export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
+    const envWorkspace = process.env.BRAINCLAW_CWD?.trim();
+    const workspaceAnchor = envWorkspace && fs.existsSync(path.join(path.resolve(envWorkspace), MEMORY_DIR, 'config.yaml'))
+        ? path.resolve(envWorkspace)
+        : undefined;
     // Walk UP from real cwd to find the outermost .brainclaw/ — this avoids
     // circular resolution when an active project narrows the workspace view.
-    const wsRoot = findOutermostBrainclawRoot(process.cwd())
+    const wsRoot = workspaceAnchor
+        ?? findOutermostBrainclawRoot(cwd)
         ?? resolveWorkspaceRoot(cwd, storeChainOptions);
     if (!wsRoot)
         return undefined;

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.5.4 on 2026-05-10T22:45:47.168Z
+// Source: brainclaw v1.6.0 on 2026-05-22T22:24:08.363Z
 export const FACTS = {
-  "version": "1.5.4",
-  "generated_at": "2026-05-10T22:45:47.168Z",
+  "version": "1.6.0",
+  "generated_at": "2026-05-22T22:24:08.363Z",
   "tools": {
-    "count": 60,
-    "published_count": 59,
+    "count": 62,
+    "published_count": 61,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -30,10 +30,12 @@ export const FACTS = {
       "bclaw_check_security",
       "bclaw_read_inbox",
       "bclaw_get_thread",
+      "bclaw_dispatch_status",
       "bclaw_dispatch",
       "bclaw_send_message",
       "bclaw_ack_message",
       "bclaw_setup",
+      "bclaw_init_project",
       "bclaw_write_note",
       "bclaw_quick_capture",
       "bclaw_claim",

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.5.4",
-  "generated_at": "2026-05-10T22:45:47.168Z",
+  "version": "1.6.0",
+  "generated_at": "2026-05-22T22:24:08.363Z",
   "tools": {
-    "count": 60,
-    "published_count": 59,
+    "count": 62,
+    "published_count": 61,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -28,10 +28,12 @@
       "bclaw_check_security",
       "bclaw_read_inbox",
       "bclaw_get_thread",
+      "bclaw_dispatch_status",
       "bclaw_dispatch",
       "bclaw_send_message",
       "bclaw_ack_message",
       "bclaw_setup",
+      "bclaw_init_project",
       "bclaw_write_note",
       "bclaw_quick_capture",
       "bclaw_claim",

package/docs/cli.md

@@ -62,9 +62,9 @@ brainclaw --cwd /other/path status   # one-off override without switching
 
 ## Initialize and Inspect
 
-### `brainclaw setup`
-
-Global onboarding wizard — detects AI agents, installs global Brainclaw prerequisites, installs agent/MCP config, gitignores generated workspace-local integration files, and initialises multiple repositories in one pass. This is the required machine-level bootstrap before `brainclaw init`. It scans each root itself plus its direct child repositories, and ignores internal Brainclaw memory repos such as `.brainclaw/`.
+### `brainclaw setup`
+
+Global onboarding wizard — bootstraps the machine, detects AI agents, installs global Brainclaw prerequisites, writes agent/MCP config, gitignores generated workspace-local integration files, and initialises multiple repositories in one pass. It scans each root itself plus its direct child repositories, and ignores internal Brainclaw memory repos such as `.brainclaw/`.
 
 | Option | Description |
 |---|---|
@@ -80,32 +80,57 @@ brainclaw setup --roots ~/Projects --agents detected    # scan ~/Projects, confi
 brainclaw setup --roots ~/Projects,~/work --agents all  # all agents, multiple roots
 ```
 
-**MCP usage (agent-driven):** Use `bclaw_setup` with the resume pattern — call without `step` to start, then pass `step` + `choice` to advance through each stage (`project_roots` → `repo_selection` → `agent_selection`).
-
----
-
-### `brainclaw init`
-
-Initialize workspace state for the current project root. Detects the AI agent environment, writes to its native instruction file, and installs a git post-merge hook for automatic claim release. `brainclaw setup` must have been run first on this machine. Do not run `init` from inside `.brainclaw/`; that directory is Brainclaw's own memory store, not a project root.
-
-| Option | Description |
-|---|---|
-| `-y, --yes` | Non-interactive, accept all defaults |
-| `--force` | Overwrite existing initialization |
-| `--compact` | Generate a compact instruction file |
-| `--topology <value>` | Storage topology (e.g. `sidecar` to store outside the repo) |
-| `--project-mode <value>` | Project mode (e.g. `multi-project`) |
+**MCP usage (agent-driven):** Use `bclaw_setup` with the resume pattern — call without `step` to start, then pass `step` + `choice` to advance through each stage (`project_roots` → `repo_selection` → `agent_selection`).
+
+---
+
+### `brainclaw setup-machine`
+
+Machine-only onboarding. Detects available agents, writes the machine-level MCP/user config Brainclaw manages, refreshes machine inventory, and stops there — no repository scan, no `.brainclaw/` init in the current working tree.
+
+| Option | Description |
+|---|---|
+| `--agents <agents>` | Agents to configure: `all`, `detected`, or comma-separated names |
+| `-y, --yes` | Accept all defaults non-interactively |
+
+```bash
+brainclaw setup-machine
+brainclaw setup-machine --yes
+brainclaw setup-machine --agents codex,cursor
+```
+
+Use this when Brainclaw is new on the current machine and you want to make the MCP surface visible to your coding agent before touching any project. The usual follow-up is `brainclaw init` inside the project you want to create or refresh.
+
+---
+
+### `brainclaw init`
+
+Create or refresh Brainclaw state for the current project root. Detects the AI agent environment, writes or refreshes its native instruction file, and installs a git post-merge hook for automatic claim release. `init` is now safe to rerun on an already initialized project: it preserves canonical memory and refreshes the managed Brainclaw and detected-agent files. Do not run `init` from inside `.brainclaw/`; that directory is Brainclaw's own memory store, not a project root.
+
+| Option | Description |
+|---|---|
+| `-y, --yes` | Non-interactive, accept all defaults |
+| `--force` | Rebuild managed initialization from Brainclaw defaults while preserving canonical memory data |
+| `--compact` | Generate a compact instruction file |
+| `--topology <value>` | Storage topology (e.g. `sidecar` to store outside the repo) |
+| `--project-mode <value>` | Project mode (e.g. `multi-project`) |
 | `--project-strategy <value>` | Project strategy (e.g. `folder`) |
 | `--no-analyze-repo` | Skip automatic repository analysis |
 | `--scan` | Scan repository for existing conventions |
 
 ```bash
-brainclaw init
-brainclaw init -y
-brainclaw init --force
-brainclaw init --topology sidecar
-brainclaw init --project-mode multi-project --project-strategy folder
-```
+brainclaw init
+brainclaw init -y
+brainclaw init --force
+brainclaw init --topology sidecar
+brainclaw init --project-mode multi-project --project-strategy folder
+```
+
+Common onboarding split:
+
+- new machine → `brainclaw setup-machine --yes`
+- current project (new or already using Brainclaw) → `brainclaw init`
+- explicit second agent on an existing Brainclaw project → `brainclaw enable-agent <agent-name>`
 
 ### `brainclaw machine-profile`
 
@@ -758,9 +783,29 @@ brainclaw claim list --agent copilot --project auth
 brainclaw claim list --all --json
 ```
 
-Legacy alias: `brainclaw list-claims`
-
-### `brainclaw list-agents`
+Legacy alias: `brainclaw list-claims`
+
+### `brainclaw assignment list`
+
+List assignments. By default this shows only non-terminal assignments; use `--all` to include `completed`, `cancelled`, `expired`, and `rerouted`.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `--all` | Include terminal assignments |
+| `--status <status>` | Filter by assignment status |
+| `--agent <name>` | Filter by agent |
+| `--claim <id>` | Filter by claim ID |
+| `--plan <id>` | Filter by plan ID |
+| `--sequence <id>` | Filter by sequence ID |
+
+```bash
+brainclaw assignment list
+brainclaw assignment list --status blocked
+brainclaw assignment list --all --json
+```
+
+### `brainclaw list-agents`
 
 List registered agent and human identities.
 
@@ -1113,9 +1158,49 @@ brainclaw claim release clm_001
 brainclaw claim release clm_001 --plan-status done
 ```
 
-Legacy alias: `brainclaw release-claim <id>`
-
-### `brainclaw release-claims`
+Legacy alias: `brainclaw release-claim <id>`
+
+### `brainclaw assignment get <id>`
+
+Show one assignment with its lifecycle timestamps and links.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+```bash
+brainclaw assignment get asgn_001
+brainclaw assignment get asgn_001 --json
+```
+
+### `brainclaw assignment update <id>`
+
+Advance an assignment to a supported lifecycle status through the canonical assignment FSM.
+
+| Option | Description |
+|---|---|
+| `--status <status>` | Target assignment status |
+| `--reason <text>` | Optional status reason recorded on the assignment |
+
+```bash
+brainclaw assignment update asgn_001 --status started
+brainclaw assignment update asgn_001 --status cancelled --reason "Supervisor aborted the lane"
+```
+
+### `brainclaw assignment cancel <id>`
+
+Supervisor/admin shortcut for `brainclaw assignment update <id> --status cancelled`.
+
+| Option | Description |
+|---|---|
+| `--reason <text>` | Optional cancellation reason recorded on the assignment |
+
+```bash
+brainclaw assignment cancel asgn_001
+brainclaw assignment cancel asgn_001 --reason "Superseded by reroute"
+```
+
+### `brainclaw release-claims`
 
 Release multiple claims derived from a Git diff.