brainclaw 1.5.3 → 1.5.5

package/LICENSE

@@ -1,74 +1,21 @@
-Business Source License 1.1
-
-Licensor:             Juan Berdah
-Licensed Work:        brainclaw
-                      The Licensed Work is (c) 2024-2026 Juan Berdah
-Change Date:          Four years from the release date of each version
-Change License:       MIT License
-
-For information about alternative licensing arrangements, contact the Licensor.
-
----
-
-Parameters
-
-Licensor:             Juan Berdah
-Licensed Work:        brainclaw
-Additional Use Grant: You may make production use of the Licensed Work, including use
-                      for internal business operations, provided that you do not use the
-                      Licensed Work to build or offer a competing product or service that
-                      provides shared agent memory, coordination, or context management
-                      for coding agents or development teams.
-Change Date:          Four years after the release date of each version
-Change License:       MIT License
-
----
-
-Notice
-
-The Business Source License (this document, or the "License") is not an Open Source
-license. However, the Licensed Work will eventually be made available under an Open
-Source License, as stated in this License.
-
-Use Limitation: The additional use grant in the Parameters specifies the permitted
-production use. If your use case falls outside that grant, you need a separate
-commercial license from the Licensor.
-
-License text
-
-The Licensor hereby grants you the right to copy, modify, create derivative works,
-redistribute, and make non-production use of the Licensed Work. The Licensor may
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly available
-distribution of a specific version of the Licensed Work under this License, whichever
-comes first, the Licensor hereby grants you rights under the terms of the Change
-License, and the rights granted in the paragraph above terminate.
-
-If your use of the Licensed Work does not comply with the requirements currently in
-effect as described in this License, you must purchase a commercial license from the
-Licensor, its affiliated entities, or authorized resellers, or you must refrain from
-using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative works of the
-Licensed Work, are subject to this License. This License applies separately for each
-version of the Licensed Work and the Change Date may vary for each version of the
-Licensed Work released by the licensor.
-
-You must conspicuously display this License on each original or modified copy of the
-Licensed Work. If you receive the Licensed Work in original or modified form from a
-third party, the terms and conditions set forth in this License apply to your use of
-that work.
-
-Any use of the Licensed Work in violation of this License will automatically terminate
-your rights under this License for the current and all future versions of the Licensed
-Work.
-
-This License does not grant you any right in any trademark or logo of Licensor or its
-affiliates (provided that you may use a trademark or logo of Licensor as expressly
-required by this License).
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS
-IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR
-IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
-PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+MIT License
+
+Copyright (c) 2024-2026 Juan Berdah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -108,28 +108,52 @@ If you want the least surprising setup today, use Linux first. If you are on Win
 
 ---
 
-## Get Started
-
-### 1. Install
-
-```bash
-npm install -g brainclaw
-```
-
-### 2. Initialize a project
-
-```bash
-cd your-project
-brainclaw init
-```
-
-This creates `.brainclaw/` in your repo, detects your coding agent, writes MCP config and instruction files, and sets up session hooks. It takes about 10 seconds.
-
-### 3. Restart your agent
-
-Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
-
-### 4. Start working
+## Get Started
+
+### 1. Let your coding agent lead
+
+The smoothest first-run path is agent-first:
+
+1. ask your coding agent to inspect the package and explain what brainclaw does
+2. ask it to install brainclaw and initialize or join the project you're working on
+3. use the CLI yourself when you need an explicit operator or fallback path
+
+If you want to drive setup manually, use the steps below.
+
+### 2. Install
+
+```bash
+npm install -g brainclaw
+```
+
+### 3. Bootstrap this machine
+
+```bash
+brainclaw setup-machine --yes
+```
+
+This detects the installed agents on the current machine, writes the machine-level MCP and user config Brainclaw manages, and does **not** scan or initialize repositories.
+
+### 4. Initialize or refresh the current project
+
+```bash
+cd your-project
+brainclaw init
+```
+
+`brainclaw init` is now safe to rerun. It creates `.brainclaw/` when the project is new, or refreshes the managed Brainclaw and agent integration files when the project already has memory.
+
+If you are explicitly adding another agent to an existing Brainclaw project, use:
+
+```bash
+brainclaw enable-agent <agent-name>
+```
+
+### 5. Restart your agent
+
+Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
+
+### 6. Start working
 
 Pick one of the canonical entry points depending on what you're doing:
 
@@ -161,7 +185,7 @@ For agents without MCP (e.g. Copilot reads `.github/copilot-instructions.md`), r
 brainclaw export --detect --write
 ```
 
-### 5. Verify it works
+### 7. Verify it works
 
 ```bash
 brainclaw status          # see active sessions, claims, plans
@@ -172,11 +196,11 @@ brainclaw agent-board     # see what each agent is doing
 
 To configure brainclaw for all your repos and agents at once:
 
-```bash
-brainclaw setup --yes
-```
-
-This scans your projects, detects installed agents (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.), and writes MCP configs for each.
+```bash
+brainclaw setup --yes
+```
+
+This is the broader multi-repo wizard. It bootstraps the machine, scans your project roots, and initializes selected repositories in one pass.
 
 ### Existing projects
 
@@ -380,15 +404,15 @@ For older releases (v0.x and the early v1.0 launch series), `git log` on `master
 
 ---
 
-## License
-
-Current releases of brainclaw are published under the [Business Source License 1.1](LICENSE) — (c) 2024-2026 Juan Berdah.
-
-The long-term direction is simpler than the current wording might suggest:
-
-- the local-first brainclaw core is intended to move to MIT after the closed beta
-- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
-
-The intended MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
+## License
+
+brainclaw core is published under the [MIT License](LICENSE) — (c) 2024-2026 Juan Berdah.
+
+The licensing split is simple:
+
+- the local-first brainclaw core is MIT
+- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
+
+The MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
 
 The goal is not to close brainclaw down. The goal is to keep the local-first core open and genuinely useful on its own, while keeping hosted collaboration features separate.

package/dist/cli.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import { Command } from 'commander';
 import { runInit } from './commands/init.js';
-import { runSetup } from './commands/setup.js';
+import { runSetup, runSetupMachine } from './commands/setup.js';
 import { runUpgrade } from './commands/upgrade.js';
 import { patchAllMcpConfigs } from './core/agent-files.js';
 import { runReconcile } from './commands/reconcile.js';
@@ -47,6 +47,7 @@ import { cleanupStaleCandidates } from './core/candidates.js';
 import { runListClaims } from './commands/list-claims.js';
 import { runReleaseClaim } from './commands/release-claim.js';
 import { runClaimResource } from './commands/claim-resource.js';
+import { runAssignmentResource } from './commands/assignment-resource.js';
 import { runMemoryCommand } from './commands/memory.js';
 import { runReleaseClaims } from './commands/release-claims.js';
 import { runAgentBoard } from './commands/agent-board.js';
@@ -109,6 +110,42 @@ const program = new Command();
 function collect(value, previous) {
     return [...previous, value];
 }
+function parseLeadingGlobalOptions(argv) {
+    const result = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith('-')) {
+            break;
+        }
+        if (token === '--verbose') {
+            result.verbose = true;
+            continue;
+        }
+        if (token === '--debug') {
+            result.debug = true;
+            continue;
+        }
+        if (token === '--cwd') {
+            result.cwd = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (token.startsWith('--cwd=')) {
+            result.cwd = token.slice('--cwd='.length);
+            continue;
+        }
+        if (token === '--project') {
+            result.project = argv[i + 1];
+            i++;
+            continue;
+        }
+        if (token.startsWith('--project=')) {
+            result.project = token.slice('--project='.length);
+            continue;
+        }
+    }
+    return result;
+}
 function isCodevEnabled() {
     return process.env.BRAINCLAW_ENABLE_CODEV === '1';
 }
@@ -121,11 +158,11 @@ program
     .option('--cwd <path>', 'Override working directory for this invocation')
     .option('--project <name>', 'Run the command against a linked project (cross_project_links or workspace store-chain child). Resolves via resolveProjectCwd; mutually exclusive with --cwd.')
     .hook('preAction', (_thisCommand, actionCommand) => {
-    const root = actionCommand.optsWithGlobals();
+    const root = parseLeadingGlobalOptions(process.argv.slice(2));
     initLogLevel({ verbose: root.verbose, debug: root.debug });
     // Skip effective cwd resolution for commands that create the store
     const cmdName = actionCommand.name();
-    const skipResolution = cmdName === 'init' || cmdName === 'setup';
+    const skipResolution = cmdName === 'init' || cmdName === 'setup' || cmdName === 'setup-machine';
     // pln#359 phase 1c — `--project <name>` resolves a linked project to an
     // absolute path via resolveProjectCwd, then feeds the same chdir flow
     // as --cwd. Mutually exclusive with --cwd to avoid ambiguity.
@@ -165,9 +202,9 @@ program
 // --- init ---
 program
     .command('init')
-    .description('Initialize project memory in .brainclaw/ storage directory')
+    .description('Initialize or refresh project memory in .brainclaw/ storage directory')
     .option('-y, --yes', 'Skip interactive wizard and use defaults')
-    .option('--force', 'Overwrite existing project memory directory')
+    .option('--force', 'Rebuild managed Brainclaw config and generated files from defaults')
     .option('--compact', 'Enable compact markdown mode')
     .option('--topology <mode>', 'Topology mode: embedded, sidecar, local-only')
     .option('--project-mode <mode>', 'Project mode: single-project, multi-project, auto')
@@ -181,7 +218,7 @@ program
 // --- setup ---
 program
     .command('setup')
-    .description('Interactive onboarding wizard — global agent install + multi-repo init')
+    .description('Interactive onboarding wizard — machine bootstrap plus multi-repo init')
     .option('--roots <paths>', 'Comma-separated root directories to scan (skips interactive prompt)')
     .option('--agents <agents>', 'Agents to configure: all, detected, or comma-separated names')
     .option('--repos <mode>', 'Repo selection: all, current, or comma-separated numbers')
@@ -189,6 +226,15 @@ program
     .action(async (options) => {
     await runSetup(options);
 });
+// --- setup-machine ---
+program
+    .command('setup-machine')
+    .description('Machine-only onboarding — detect/configure agents and MCP without scanning or initializing repositories')
+    .option('--agents <agents>', 'Agents to configure: all, detected, or comma-separated names')
+    .option('-y, --yes', 'Accept all defaults non-interactively')
+    .action(async (options) => {
+    await runSetupMachine(options);
+});
 // --- memory-log ---
 program
     .command('memory-log')
@@ -1003,6 +1049,26 @@ program
     .action((subcommand, args, options) => {
     runClaimResource(subcommand, args, { ...options, planStatus: options.planStatus, localOnly: options.localOnly });
 });
+// --- assignment ---
+program
+    .command('assignment <subcommand> [args...]')
+    .description('Manage work assignments (list, show, update, cancel)')
+    .option('--json', 'Output as JSON for list/show')
+    .option('--all', 'Include terminal assignments in list')
+    .option('--status <status>', 'Status filter for list or target status for update')
+    .option('--agent <agent>', 'Filter by agent name')
+    .option('--claim <id>', 'Filter by linked claim ID')
+    .option('--plan <id>', 'Filter by linked plan ID')
+    .option('--sequence <id>', 'Filter by linked sequence ID')
+    .option('--reason <text>', 'Optional status reason for update/cancel')
+    .action((subcommand, args, options) => {
+    runAssignmentResource(subcommand, args, {
+        ...options,
+        claim: options.claim,
+        plan: options.plan,
+        sequence: options.sequence,
+    });
+});
 // --- list-claims ---
 program
     .command('list-claims')

package/dist/commands/assignment-resource.js

@@ -0,0 +1,182 @@
+import { memoryExists } from '../core/io.js';
+import { listAssignments, loadAssignment, transitionAssignment } from '../core/assignments.js';
+import { resolveCurrentAgentName } from '../core/agent-registry.js';
+import { AssignmentStatusSchema } from '../core/schema.js';
+const TERMINAL_STATUSES = new Set(['completed', 'cancelled', 'expired', 'rerouted']);
+const KNOWN_SUBCOMMANDS = new Set(['list', 'ls', 'show', 'get', 'update', 'cancel']);
+export function runAssignmentResource(subcommand, args, options = {}) {
+    const normalized = subcommand.trim().toLowerCase();
+    if (normalized === 'list' || normalized === 'ls') {
+        runListAssignmentsCommand(options);
+        return;
+    }
+    if (normalized === 'show' || normalized === 'get') {
+        const id = args[0];
+        if (!id) {
+            console.error(`Error: assignment ${normalized} requires <id>.`);
+            process.exit(1);
+        }
+        runShowAssignmentCommand(id, options);
+        return;
+    }
+    if (normalized === 'update') {
+        const id = args[0];
+        if (!id) {
+            console.error('Error: assignment update requires <id>.');
+            process.exit(1);
+        }
+        const status = options.status;
+        if (!status) {
+            console.error('Error: assignment update requires --status <status>.');
+            process.exit(1);
+        }
+        runTransitionAssignmentCommand(id, status, options);
+        return;
+    }
+    if (normalized === 'cancel') {
+        const id = args[0];
+        if (!id) {
+            console.error('Error: assignment cancel requires <id>.');
+            process.exit(1);
+        }
+        runTransitionAssignmentCommand(id, 'cancelled', options);
+        return;
+    }
+    if (normalized.startsWith('asgn_') || KNOWN_SUBCOMMANDS.has(normalized)) {
+        console.error(`Error: unknown assignment subcommand "${subcommand}".`);
+        console.error('  Available: list, show, get, update, cancel');
+        process.exit(1);
+    }
+    console.error('Error: missing assignment subcommand.');
+    console.error('  Available: list, show, get, update, cancel');
+    process.exit(1);
+}
+function runListAssignmentsCommand(options) {
+    ensureInitialized(options.cwd);
+    const requestedStatus = parseAssignmentStatus(options.status);
+    let assignments = listAssignments(options.cwd, {
+        status: requestedStatus,
+        agent: options.agent,
+        claim_id: options.claim,
+        plan_id: options.plan,
+        sequence_id: options.sequence,
+    });
+    if (!options.all && !requestedStatus) {
+        assignments = assignments.filter((assignment) => !TERMINAL_STATUSES.has(assignment.status));
+    }
+    if (options.json) {
+        console.log(JSON.stringify(assignments, null, 2));
+        return;
+    }
+    if (assignments.length === 0) {
+        console.log(options.all ? 'No assignments.' : 'No active assignments.');
+        return;
+    }
+    console.log(`${assignments.length} ${options.all ? 'assignment(s)' : 'active assignment(s)'}:`);
+    console.log('');
+    for (const assignment of assignments) {
+        const extras = [];
+        if (assignment.plan_id)
+            extras.push(`plan ${assignment.plan_id}`);
+        if (assignment.claim_id)
+            extras.push(`claim ${assignment.claim_id}`);
+        if (assignment.sequence_id)
+            extras.push(`sequence ${assignment.sequence_id}`);
+        if (assignment.worktree_path)
+            extras.push(`worktree ${assignment.worktree_path}`);
+        const suffix = extras.length > 0 ? ` [${extras.join(', ')}]` : '';
+        console.log(`  [${assignment.id}] ${assignment.agent} (${assignment.status}) -> ${assignment.scope}: ${assignment.description}${suffix}`);
+    }
+}
+function runShowAssignmentCommand(id, options) {
+    ensureInitialized(options.cwd);
+    const assignment = requireAssignment(id, options.cwd);
+    if (options.json) {
+        console.log(JSON.stringify(assignment, null, 2));
+        return;
+    }
+    console.log(`Assignment: ${assignment.id}`);
+    console.log(`  Agent:        ${assignment.agent}`);
+    console.log(`  Status:       ${assignment.status}`);
+    console.log(`  Scope:        ${assignment.scope}`);
+    console.log(`  Description:  ${assignment.description}`);
+    console.log(`  Claim:        ${assignment.claim_id}`);
+    if (assignment.message_id)
+        console.log(`  Message:      ${assignment.message_id}`);
+    if (assignment.plan_id)
+        console.log(`  Plan:         ${assignment.plan_id}`);
+    if (assignment.sequence_id)
+        console.log(`  Sequence:     ${assignment.sequence_id}`);
+    if (assignment.session_id)
+        console.log(`  Session:      ${assignment.session_id}`);
+    if (assignment.status_reason)
+        console.log(`  Reason:       ${assignment.status_reason}`);
+    if (assignment.worktree_path)
+        console.log(`  Worktree:     ${assignment.worktree_path}`);
+    console.log(`  Created:      ${assignment.created_at}`);
+    if (assignment.updated_at)
+        console.log(`  Updated:      ${assignment.updated_at}`);
+    if (assignment.offered_at)
+        console.log(`  Offered:      ${assignment.offered_at}`);
+    if (assignment.accepted_at)
+        console.log(`  Accepted:     ${assignment.accepted_at}`);
+    if (assignment.started_at)
+        console.log(`  Started:      ${assignment.started_at}`);
+    if (assignment.completed_at)
+        console.log(`  Completed:    ${assignment.completed_at}`);
+    if (assignment.cancelled_at)
+        console.log(`  Cancelled:    ${assignment.cancelled_at}`);
+    if (assignment.failed_at)
+        console.log(`  Failed:       ${assignment.failed_at}`);
+    if (assignment.blocked_at)
+        console.log(`  Blocked:      ${assignment.blocked_at}`);
+    if (assignment.timed_out_at)
+        console.log(`  Timed out:    ${assignment.timed_out_at}`);
+    if (assignment.expired_at)
+        console.log(`  Expired:      ${assignment.expired_at}`);
+    if (assignment.rerouted_at)
+        console.log(`  Rerouted:     ${assignment.rerouted_at}`);
+}
+function runTransitionAssignmentCommand(id, statusInput, options) {
+    ensureInitialized(options.cwd);
+    const nextStatus = parseAssignmentStatus(statusInput, 'status');
+    const actor = resolveCurrentAgentName(options.cwd);
+    try {
+        const result = transitionAssignment(id, nextStatus, {
+            actor,
+            status_reason: options.reason,
+        }, options.cwd);
+        const verb = nextStatus === 'cancelled' ? 'cancelled' : 'updated';
+        console.log(`✔ Assignment ${verb}: [${result.assignment.id}] ${result.previous_status} -> ${result.assignment.status}`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+function ensureInitialized(cwd) {
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+}
+function requireAssignment(id, cwd) {
+    const assignment = loadAssignment(id, cwd);
+    if (!assignment) {
+        console.error(`Error: assignment not found: ${id}`);
+        process.exit(1);
+    }
+    return assignment;
+}
+function parseAssignmentStatus(value, label = 'filter') {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = AssignmentStatusSchema.safeParse(value);
+    if (!parsed.success) {
+        console.error(`Error: invalid ${label} '${value}'. Expected one of: ${AssignmentStatusSchema.options.join(', ')}`);
+        process.exit(1);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=assignment-resource.js.map