bullswarm 0.10.0 → 0.10.2

package/AGENTS.md

@@ -37,7 +37,7 @@ content. Published as `bullswarm` on npm.
 ## Development
 
 ```bash
-npm test            # 195 tests, no network needed (meters read from cache)
+npm test            # 232 tests, no network needed (meters read from cache)
 node bin/bullswarm.js doctor --json   # readiness report
 node bin/bullswarm.js workflow list   # discover workflows
 node bin/bullswarm.js workflow runs   # ongoing workflow instances

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # bullswarm changelog
 
+## 0.10.2 — cross-agent skill integration
+
+- Added explicit `bullswarm integrate status|install|remove` support for Codex,
+  Claude, and Grok. Installation registers one packaged `bullswarm` skill with
+  all selected agents and writes concise marker-delimited global awareness
+  rules; removal touches only Bullswarm-managed links and blocks.
+- Added recoverable `integrate retire-legacy --yes` migration for the retired
+  Claude `offload` skill. Detection is read-only and retirement always moves the
+  old skill into `~/.claude/skills-archive/`.
+- Added recursion-aware global guidance: a worker with `BULLSWARM_DEPTH` set
+  performs its assigned task directly instead of casually spawning another
+  swarm.
+- Renamed the published agent skill from `bullswarm-setup` to `bullswarm` and
+  documented single-task, zero-graph goal, fixed-workflow, observation, and
+  integration paths together.
+- Corrected README language so agent/time targets are advisory while graph
+  expansion limits remain hard safeguards.
+
+## 0.10.1 — initiated-time workflow history search
+
+- Added `workflow runs --since <time> --until <time>` filtering against the
+  workflow's initiation timestamp (`startedAt`), with an inclusive lower bound
+  and exclusive upper bound.
+- Added `--from`/`--to` and `--started-after`/`--started-before` aliases plus
+  ISO timestamps, local dates, calendar keywords, and relative durations such
+  as `7d`.
+- Historical listing now falls back to `report.startedAt` when an older state
+  record lacks its initiation timestamp, and JSON output reports the normalized
+  range used for the audit.
+
 ## 0.10.0 — battle-tested advisory orchestration and agent activity
 
 - Made `maxAgents` and `maxWorkflowSeconds` advisory planning targets instead

package/README.md

@@ -23,8 +23,24 @@ Every delegate output is judged by content before it counts.
 
 ```bash
 npm install -g bullswarm   # or: node bin/bullswarm.js directly from a checkout
+bullswarm integrate install --agents codex,claude,grok --yes
 ```
 
+The integration command registers Bullswarm's packaged `bullswarm` skill with
+Codex, Claude, and Grok and appends a concise, marker-delimited awareness rule
+to each agent's global instructions. It is explicit, idempotent, and reversible:
+
+```bash
+bullswarm integrate status --json
+bullswarm integrate remove --agents codex,claude,grok --yes
+```
+
+If the retired pre-Bullswarm Claude `offload` skill is detected, status reports
+it without changing it. Archive it recoverably with
+`bullswarm integrate retire-legacy --yes`. The awareness rule prevents workers
+already launched by Bullswarm (`BULLSWARM_DEPTH` is set) from casually
+re-delegating and creating recursive swarms.
+
 ## Quick start
 
 ```bash
@@ -42,6 +58,7 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 | Verb | Purpose |
 |---|---|
 | `setup` | Discover installed agent CLIs, show quota state, toggle pools, suggest a routing table, write config. Approval-gated, idempotent. |
+| `integrate` | Register or remove the canonical Bullswarm skill and global awareness rules for Codex, Claude, and Grok. |
 | `run` | route → dispatch → watch → verify → one JSON verdict |
 | `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
 | `pools` | Show each pool's meter state, pace position, quarantine status |
@@ -107,7 +124,7 @@ orchestrator by live quota surplus. The orchestrator observes durable evidence,
 and decides when another expansion or verification is necessary. Bullswarm
 validates the proposal, owns agent/process selection, routes workers, and calls
 the orchestrator again until completion, cancellation, failure, approval, or a
-budget limit. No initial phases, prompts, JSON schema, or agent choice are
+hard graph-growth safeguard. No initial phases, prompts, JSON schema, or agent choice are
 required from the user.
 
 The detached response includes a short ID and exact observation commands:
@@ -128,9 +145,10 @@ bullswarm workflow goal --resume <shortId> --json
 ```
 
 `--orchestrator <pool>` exists for controlled testing; ordinary use should
-leave selection on `auto`. Hard limits can be adjusted with `--max-agents`,
-`--max-expansion-rounds`, `--max-actions`, `--max-items-per-expansion`, and
-`--max-workflow-seconds`. Interactive setup also records a worktree-isolation
+leave selection on `auto`. `--max-agents` and `--max-workflow-seconds` are
+advisory planning targets; hard graph-growth safeguards are adjusted with
+`--max-expansion-rounds`, `--max-actions`, and `--max-items-per-expansion`.
+Interactive setup also records a worktree-isolation
 preference (`agent-decides`, `off`, or `required`); Bullswarm communicates that
 policy to the orchestrator without imposing repository topology itself.
 
@@ -173,6 +191,9 @@ bullswarm workflow runs                    # ongoing only (default)
 bullswarm workflow runs --all              # ongoing + historical
 bullswarm workflow runs --historical       # only historical
 bullswarm workflow runs --name audit-code  # filter by workflow
+bullswarm workflow runs --all --since 7d   # initiated in the last 7 days
+bullswarm workflow runs --historical --since yesterday --until today
+bullswarm workflow runs --all --from 2026-08-20 --to 2026-08-27
 bullswarm workflow runs --limit 20         # cap the result count
 bullswarm workflow runs show <shortId>     # state + report + summary
 bullswarm runs show <shortId>              # top-level shorthand
@@ -182,6 +203,14 @@ bullswarm workflow runs delete <shortId> --yes    # remove the run dir
 bullswarm workflow run audit-code --resume <shortId>
 ```
 
+Run-history time filters always compare when the workflow was initiated
+(`startedAt`), never when it finished. `--since` is inclusive and `--until` is
+exclusive; `--started-after`/`--from` and `--started-before`/`--to` are aliases.
+Values accept ISO timestamps, local `YYYY-MM-DD` dates, `today`, `yesterday`,
+`tomorrow`, `now`, or relative durations such as `30m`, `24h`, `7d`, and `2w`.
+Time filters preserve the existing scope, so use `--all` or `--historical` when
+auditing completed runs.
+
 ### Live workflow dashboard
 
 For ordinary observation, use the non-interactive watcher. It prints only when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: bullswarm-setup
+name: bullswarm
 description: Use when you want to offload work to coding-agent subscriptions or run a self-contained goal across heterogeneous providers. bullswarm can accept one goal, select an orchestrator, expand and execute a bounded plan, verify the outcome, and expose the whole run through CLI state and events. Use `bullswarm workflow goal` for ordinary multi-step work, an explicit workflow draft when the graph itself is the contract, and `bullswarm run` for one bounded task. Every verb self-initializes.
 ---
 
@@ -10,6 +10,16 @@ CLI subscription has the most quota headroom. Every delegate output is
 judged by **content**, not exit code. A non-zero exit is never a success; a
 `verified` output is.
 
+This skill is registered globally by:
+
+```bash
+bullswarm integrate install --agents codex,claude,grok --yes
+```
+
+If `BULLSWARM_DEPTH` is already set, you are a Bullswarm delegate. Complete the
+assigned task directly; do not recursively invoke Bullswarm unless the task
+explicitly requires another bounded delegation.
+
 ## When to reach for it
 
 You should consider bullswarm when **any** of the following apply:
@@ -166,10 +176,19 @@ Every run gets a 6-character shortId (Crockford-style alphabet, no
 bullswarm workflow runs                       # ongoing only (default)
 bullswarm workflow runs --all                 # ongoing + historical
 bullswarm workflow runs --name <workflow>     # filter by workflow name
+bullswarm workflow runs --all --since 7d      # initiated in the last 7 days
+bullswarm workflow runs --historical --since yesterday --until today
 bullswarm workflow runs show <shortId>        # state + report + summary
 bullswarm workflow runs delete <shortId> --yes
 ```
 
+Historical time ranges filter the workflow's initiation time (`startedAt`),
+not completion time. `--since` is inclusive and `--until` is exclusive, with
+`--from`/`--to` and `--started-after`/`--started-before` aliases. Bounds accept
+ISO timestamps, local dates, today/yesterday/tomorrow/now, or durations such as
+`7d`. Add `--all` or `--historical`; time filters do not silently change the
+normal ongoing-only scope.
+
 Before authoring or choosing a workflow, agents can inspect the live execution
 fabric and the workflow document itself:
 
@@ -297,6 +316,10 @@ You do NOT need to set up bullswarm. Every verb self-initializes:
 bullswarm doctor --json
 ```
 
+Self-initialization prepares routing and connectors; it does not silently edit
+global agent instructions. Inspect or explicitly install agent awareness with
+`bullswarm integrate status --json` and `bullswarm integrate install --yes`.
+
 The output has a `checks[]` array with one entry per readiness concern
 (config, connectors, meters, offload-capable) and a `nextActions[]` list
 of exact commands to fix anything missing.

package/src/cli.js

@@ -16,6 +16,7 @@ import { getVersion } from './lib/version.js';
 import { release } from './lib/release.js';
 import { cmdWorkflow } from './workflow/cli.js';
 import { cmdStrategy, maybeRefreshStrategy } from './strategy-cli.js';
+import { cmdIntegrate, installIntegration } from './integrate.js';
 
 export function getBullswarmDir() {
   const h = process.env.BULLSWARM_HOME?.trim();
@@ -31,8 +32,10 @@ function parseArgs(argv) {
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i].startsWith('--')) {
-      const key = argv[i].slice(2);
+      const eq = argv[i].indexOf('=');
+      const key = argv[i].slice(2, eq > 0 ? eq : undefined);
       if (key === 'json') args.json = true;
+      else if (eq > 0) args[key] = argv[i].slice(eq + 1);
       else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) args[key] = argv[++i];
       else args[key] = true;
     } else rest.push(argv[i]);
@@ -295,12 +298,20 @@ async function cmdSetup(opts) {
       const report = await refreshStrategy(getBullswarmDir());
       strategy = applyStrategyRecommendations(getBullswarmDir(), report);
     }
-    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r, strategy }, null, 2));
+    let integration = null;
+    if (opts.yes && opts.integrate) {
+      integration = installIntegration({
+        agents: opts.agents,
+        approved: true,
+      });
+    }
+    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r, strategy, integration }, null, 2));
     else {
       console.log(`setup complete (${r.reason}): enabled ${r.enabledPools.join(', ')}`);
       if (r.repaired.length) console.log(`repaired connector files: ${r.repaired.join(', ')}`);
       console.log(`model strategy: ${r.strategyCommand} (discovers models and refreshes tier suggestions)`);
       if (strategy) console.log(`strategy autopilot: applied ${Object.keys(strategy.applied).join(', ')} tiers; refresh every ${strategy.policy.refreshHours}h`);
+      if (integration) console.log('agent integration: installed (inspect with bullswarm integrate status)');
     }
     return 0;
   }
@@ -413,6 +424,8 @@ export async function main(argv) {
       return cmdWorkflow(['runs', ...rest]);
     case 'strategy':
       return cmdStrategy(rest, { bullswarmDir: getBullswarmDir() });
+    case 'integrate':
+      return cmdIntegrate(opts);
     case 'version':
     case '--version':
       console.log(getVersion());
@@ -421,7 +434,7 @@ export async function main(argv) {
       return cmdRelease(opts);
     default:
       console.error(
-        `unknown verb "${verb}". try: setup | run | health | pools | strategy | doctor | workflow | runs | version | release`,
+        `unknown verb "${verb}". try: setup | integrate | run | health | pools | strategy | doctor | workflow | runs | version | release`,
       );
       return 2;
   }

package/src/integrate.js

@@ -0,0 +1,265 @@
+// bullswarm integrate — make the published agent guide discoverable by coding CLIs.
+//
+// Integration is explicit, idempotent, and reversible. The full operating
+// procedure remains in skill/SKILL.md; global instruction files receive only a
+// compact trigger policy so CLI documentation cannot drift in three places.
+
+import {
+  existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync,
+  symlinkSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_SOURCE = fileURLToPath(new URL('../skill', import.meta.url));
+const MARKER_BEGIN = '<!-- bullswarm:begin v2 -->';
+const MARKER_END = '<!-- bullswarm:end -->';
+const MARKER_RE = /<!-- bullswarm:begin v\d+ -->[\s\S]*?<!-- bullswarm:end -->\n?/;
+
+const AGENT_LAYOUT = {
+  codex: { skill: ['.codex', 'skills', 'bullswarm'], instructions: ['.codex', 'AGENTS.md'] },
+  claude: { skill: ['.claude', 'skills', 'bullswarm'], instructions: ['.claude', 'CLAUDE.md'] },
+  grok: { skill: ['.grok', 'skills', 'bullswarm'], instructions: ['.grok', 'AGENTS.md'] },
+};
+
+export const INTEGRATION_AGENTS = Object.freeze(Object.keys(AGENT_LAYOUT));
+
+export function awarenessBlock() {
+  return `${MARKER_BEGIN}
+## Bullswarm delegation
+
+Bullswarm is available for bounded external delegation. When delegation,
+offloading, independent verification, or autonomous multi-step execution is
+requested, read the \`bullswarm\` skill before acting. Use \`bullswarm run\` for
+one bounded task, \`bullswarm workflow goal\` for ordinary autonomous multi-step
+work, and workflow drafts only when the graph itself is the contract. Treat
+returned artifacts and verification as evidence, not authority. This policy
+supersedes retired pre-Bullswarm \`offload\` routing instructions. If
+\`BULLSWARM_DEPTH\` is already set, perform the assigned task directly and do
+not recursively invoke Bullswarm unless the task explicitly requires it.
+${MARKER_END}`;
+}
+
+export function applyAwarenessBlock(filePath, { approved }) {
+  if (!approved) return { changed: false, reason: 'not approved' };
+  const existing = readOptional(filePath);
+  const stripped = existing.replace(MARKER_RE, '').trimEnd();
+  const next = stripped ? `${stripped}\n\n${awarenessBlock()}\n` : `${awarenessBlock()}\n`;
+  mkdirSync(dirname(filePath), { recursive: true });
+  if (next === existing) return { changed: false, reason: 'already current' };
+  writeFileSync(filePath, next);
+  return { changed: true, reason: existing.match(MARKER_RE) ? 'updated' : 'installed' };
+}
+
+export function removeAwarenessBlock(filePath, { approved }) {
+  if (!approved) return { changed: false, reason: 'not approved' };
+  if (!existsSync(filePath)) return { changed: false, reason: 'not installed' };
+  const existing = readFileSync(filePath, 'utf8');
+  const next = existing.replace(MARKER_RE, '').trimEnd();
+  if (next === existing.trimEnd()) return { changed: false, reason: 'not installed' };
+  writeFileSync(filePath, next ? `${next}\n` : '');
+  return { changed: true, reason: 'removed' };
+}
+
+export function awarenessBlockPresent(filePath) {
+  return MARKER_RE.test(readOptional(filePath));
+}
+
+export function parseIntegrationAgents(value) {
+  const requested = value == null || value === true
+    ? INTEGRATION_AGENTS
+    : String(value).split(',').map((item) => item.trim().toLowerCase()).filter(Boolean);
+  const unique = [...new Set(requested)];
+  const invalid = unique.filter((agent) => !INTEGRATION_AGENTS.includes(agent));
+  if (invalid.length) {
+    throw new Error(`unknown integration agent(s): ${invalid.join(', ')}; use ${INTEGRATION_AGENTS.join(', ')}`);
+  }
+  if (!unique.length) throw new Error('--agents must name at least one agent');
+  return unique;
+}
+
+export function integrationStatus({
+  homeDir = process.env.HOME ?? '', agents = INTEGRATION_AGENTS, skillSource = SKILL_SOURCE,
+} = {}) {
+  const selected = parseIntegrationAgents(agents);
+  const entries = selected.map((agent) => {
+    const paths = pathsFor(homeDir, agent);
+    return {
+      agent,
+      skillPath: paths.skillPath,
+      skill: skillLinkStatus(paths.skillPath, skillSource),
+      instructionsPath: paths.instructionsPath,
+      awareness: awarenessBlockPresent(paths.instructionsPath),
+    };
+  });
+  const legacyPath = join(homeDir, '.claude', 'skills', 'offload');
+  return {
+    ok: entries.every((entry) => entry.skill.status === 'installed' && entry.awareness),
+    skillSource,
+    agents: entries,
+    legacyOffload: {
+      path: legacyPath,
+      detected: existsSync(legacyPath),
+      action: existsSync(legacyPath)
+        ? 'bullswarm integrate retire-legacy --yes'
+        : null,
+    },
+  };
+}
+
+export function installIntegration({
+  homeDir = process.env.HOME ?? '', agents = INTEGRATION_AGENTS,
+  skillSource = SKILL_SOURCE, approved = false,
+} = {}) {
+  if (!approved) throw new Error('integration changes global agent configuration; pass --yes to approve');
+  const selected = parseIntegrationAgents(agents);
+  if (!existsSync(join(skillSource, 'SKILL.md'))) {
+    throw new Error(`packaged Bullswarm skill is missing: ${join(skillSource, 'SKILL.md')}`);
+  }
+  for (const agent of selected) {
+    const { skillPath } = pathsFor(homeDir, agent);
+    if (skillLinkStatus(skillPath, skillSource).status === 'conflict') {
+      throw new Error(`refusing to replace non-Bullswarm skill path: ${skillPath}`);
+    }
+  }
+  const changes = [];
+  for (const agent of selected) {
+    const paths = pathsFor(homeDir, agent);
+    const skill = installSkillLink(paths.skillPath, skillSource);
+    const awareness = applyAwarenessBlock(paths.instructionsPath, { approved: true });
+    changes.push({ agent, skill, awareness });
+  }
+  return { action: 'install', changes, status: integrationStatus({ homeDir, agents: selected, skillSource }) };
+}
+
+export function removeIntegration({
+  homeDir = process.env.HOME ?? '', agents = INTEGRATION_AGENTS,
+  skillSource = SKILL_SOURCE, approved = false,
+} = {}) {
+  if (!approved) throw new Error('integration removal changes global agent configuration; pass --yes to approve');
+  const selected = parseIntegrationAgents(agents);
+  const changes = [];
+  for (const agent of selected) {
+    const paths = pathsFor(homeDir, agent);
+    const skill = removeSkillLink(paths.skillPath, skillSource);
+    const awareness = removeAwarenessBlock(paths.instructionsPath, { approved: true });
+    changes.push({ agent, skill, awareness });
+  }
+  return { action: 'remove', changes, status: integrationStatus({ homeDir, agents: selected, skillSource }) };
+}
+
+export function retireLegacyOffload({ homeDir = process.env.HOME ?? '', approved = false, now = new Date() } = {}) {
+  if (!approved) throw new Error('legacy offload retirement moves a user skill; pass --yes to approve');
+  const source = join(homeDir, '.claude', 'skills', 'offload');
+  if (!existsSync(source)) return { action: 'retire-legacy', changed: false, reason: 'not installed' };
+  const archiveRoot = join(homeDir, '.claude', 'skills-archive');
+  mkdirSync(archiveRoot, { recursive: true });
+  const stamp = now.toISOString().replace(/[:.]/g, '-');
+  const destination = join(archiveRoot, `offload-before-bullswarm-${stamp}`);
+  renameSync(source, destination);
+  return { action: 'retire-legacy', changed: true, source, destination, recoverable: true };
+}
+
+export function integrateUsage() {
+  return `usage: bullswarm integrate [status] [--agents codex,claude,grok] [--json]
+       bullswarm integrate install --agents codex,claude,grok --yes [--json]
+       bullswarm integrate remove --agents codex,claude,grok --yes [--json]
+       bullswarm integrate retire-legacy --yes [--json]
+
+Install registers the packaged Bullswarm skill and a concise recursion-safe
+awareness rule. Removal only deletes Bullswarm-managed symlinks and marker
+blocks. retire-legacy moves ~/.claude/skills/offload into skills-archive.`;
+}
+
+export function cmdIntegrate(opts) {
+  const subcommand = opts.rest[0] ?? 'status';
+  if (opts.help || subcommand === 'help') {
+    console.log(integrateUsage());
+    return 0;
+  }
+  let agents;
+  try {
+    agents = parseIntegrationAgents(opts.agents);
+    let result;
+    if (subcommand === 'status') result = { action: 'status', ...integrationStatus({ agents }) };
+    else if (subcommand === 'install') result = installIntegration({ agents, approved: opts.yes === true });
+    else if (subcommand === 'remove') result = removeIntegration({ agents, approved: opts.yes === true });
+    else if (subcommand === 'retire-legacy') result = retireLegacyOffload({ approved: opts.yes === true });
+    else {
+      console.error(integrateUsage());
+      return 2;
+    }
+    if (opts.json) console.log(JSON.stringify(result, null, 2));
+    else printIntegrationResult(result);
+    const ok = result.status?.ok ?? result.ok;
+    return ok === false && subcommand === 'status' ? 1 : 0;
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    return 1;
+  }
+}
+
+function pathsFor(homeDir, agent) {
+  const layout = AGENT_LAYOUT[agent];
+  return {
+    skillPath: join(homeDir, ...layout.skill),
+    instructionsPath: join(homeDir, ...layout.instructions),
+  };
+}
+
+function installSkillLink(skillPath, skillSource) {
+  const current = skillLinkStatus(skillPath, skillSource);
+  if (current.status === 'installed') return { changed: false, ...current };
+  if (current.status === 'conflict') {
+    throw new Error(`refusing to replace non-Bullswarm skill path: ${skillPath}`);
+  }
+  mkdirSync(dirname(skillPath), { recursive: true });
+  symlinkSync(skillSource, skillPath, 'dir');
+  return { changed: true, status: 'installed', path: skillPath, target: skillSource };
+}
+
+function removeSkillLink(skillPath, skillSource) {
+  const current = skillLinkStatus(skillPath, skillSource);
+  if (current.status === 'missing') return { changed: false, ...current };
+  if (current.status === 'conflict') {
+    return { changed: false, ...current, reason: 'left conflict untouched' };
+  }
+  unlinkSync(skillPath);
+  return { changed: true, status: 'missing', path: skillPath, target: skillSource };
+}
+
+function skillLinkStatus(skillPath, skillSource) {
+  let stat;
+  try { stat = lstatSync(skillPath); } catch { return { status: 'missing', path: skillPath, target: null }; }
+  if (!stat.isSymbolicLink()) return { status: 'conflict', path: skillPath, target: null };
+  const rawTarget = readlinkSync(skillPath);
+  const target = resolve(dirname(skillPath), rawTarget);
+  return {
+    status: target === resolve(skillSource) ? 'installed' : 'conflict',
+    path: skillPath,
+    target,
+  };
+}
+
+function readOptional(filePath) {
+  try { return readFileSync(filePath, 'utf8'); } catch { return ''; }
+}
+
+function printIntegrationResult(result) {
+  if (result.action === 'retire-legacy') {
+    console.log(result.changed
+      ? `✓ archived retired offload skill at ${result.destination}`
+      : 'retired offload skill is not installed');
+    return;
+  }
+  const status = result.status ?? result;
+  for (const entry of status.agents ?? []) {
+    const skill = entry.skill.status === 'installed' ? 'skill ✓' : `skill ${entry.skill.status}`;
+    const awareness = entry.awareness ? 'awareness ✓' : 'awareness missing';
+    console.log(`${entry.agent.padEnd(8)} ${skill}; ${awareness}`);
+  }
+  if (status.legacyOffload?.detected) {
+    console.log(`⚠ retired Claude offload skill detected: ${status.legacyOffload.path}`);
+    console.log(`  recoverably archive it with: ${status.legacyOffload.action}`);
+  }
+}

package/src/setup.js

@@ -5,9 +5,8 @@
 //       entry. Burn rate starts EMPTY and is labeled "learning".
 //   U2. The wizard suggests a routing table as an EDITABLE ARTIFACT, never a
 //       questionnaire.
-//   U3. CLAUDE.md / AGENTS.md integration is a DIFF with explicit approval
-//       before any write, delimited by versioned bullswarm:begin/end
-//       markers, idempotent on re-run.
+//   U3. Cross-agent skill/instruction integration requires explicit approval,
+//       uses versioned bullswarm:begin/end markers, and is idempotent.
 //   U4. `bullswarm setup` on a configured machine reports state and repairs
 //       broken connector files.
 
@@ -15,14 +14,16 @@ import { execFileSync } from 'node:child_process';
 import {
   existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync,
 } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stdin as input } from 'node:process';
 import { loadState, saveState } from './lib/state.js';
+import {
+  awarenessBlock, applyAwarenessBlock, awarenessBlockPresent,
+  installIntegration, retireLegacyOffload,
+} from './integrate.js';
 
 const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
-const MARKER_BEGIN = '<!-- bullswarm:begin v1 -->';
-const MARKER_END = '<!-- bullswarm:end -->';
 
 // --- prompting ------------------------------------------------------------
 // Sequential prompts that work identically on a TTY and with piped answers.
@@ -121,45 +122,15 @@ export function suggestRoutingTable(enabledPools) {
 // --- integration block ------------------------------------------------------------
 
 export function integrationBlock() {
-  return `${MARKER_BEGIN}
-## bullswarm offload policy
-
-When a task fits a bounded lane, prefer offloading it:
-
-    bullswarm run --lane <analyze|build|chore> --add-dir <repo-dir> --task-file <file> --json
-
-Read the verdict JSON: ok:true -> use outFile; keepOnClaude:true -> do it in-session;
-ok:false -> the why field names the failed gate. Delegate output is INPUT you verify,
-never the answer. Final synthesis, architecture decisions, and live-context work stay
-with you. Run \`bullswarm health\` after every offload round.
-${MARKER_END}`;
+  return awarenessBlock();
 }
 
 export function applyIntegrationBlock(filePath, { approved }) {
-  if (!approved) return { changed: false, reason: 'not approved' };
-  let existing = '';
-  try {
-    existing = readFileSync(filePath, 'utf8');
-  } catch {
-    /* new file */
-  }
-  const stripped = existing
-    .replace(new RegExp(`${MARKER_BEGIN}[\\s\\S]*?${MARKER_END}\n?`), '')
-    .trimEnd();
-  const next = stripped
-    ? `${stripped}\n\n${integrationBlock()}\n`
-    : `${integrationBlock()}\n`;
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, next);
-  return { changed: true };
+  return applyAwarenessBlock(filePath, { approved });
 }
 
 export function integrationBlockPresent(filePath) {
-  try {
-    return readFileSync(filePath, 'utf8').includes(MARKER_BEGIN);
-  } catch {
-    return false;
-  }
+  return awarenessBlockPresent(filePath);
 }
 
 // --- repair ---------------------------------------------------------------
@@ -398,21 +369,25 @@ export async function runWizard(bullswarmDir, opts = {}) {
     console.log('  strategy autopilot: off (enable later with bullswarm strategy apply --yes)');
   }
 
-  // 6. Integration blocks — diff + approval
-  for (const [label, path] of [
-    ['CLAUDE.md', join(process.env.HOME ?? '', '.claude', 'CLAUDE.md')],
-    ['AGENTS.md', join(process.cwd(), 'AGENTS.md')],
-  ]) {
-    const present = integrationBlockPresent(path);
-    const preview = present
-      ? 'block already present (idempotent re-run)'
-      : `will append to ${path}:\n\n${integrationBlock()}\n`;
-    console.log(`\n${label}: ${preview}`);
-    const ans = (
-      await rl.question(`write ${label} integration block? [y/N] `)
-    ).trim().toLowerCase();
-    const result = applyIntegrationBlock(path, { approved: ans === 'y' && !present });
-    console.log(result.changed ? `  wrote ${path}` : `  skipped ${label}`);
+  // 6. Cross-agent integration — one canonical skill plus concise global
+  // awareness rules. Nothing is written without this explicit answer.
+  const integrateAnswer = (
+    await rl.question('install Bullswarm skill for Codex, Claude, and Grok? [y/N] ')
+  ).trim().toLowerCase();
+  if (integrateAnswer === 'y' || integrateAnswer === 'yes') {
+    const integrated = installIntegration({ approved: true });
+    console.log(`  agent integration: ${integrated.status.ok ? 'ready' : 'incomplete'}`);
+    if (integrated.status.legacyOffload.detected) {
+      const retireAnswer = (
+        await rl.question('archive the retired Claude offload skill? [y/N] ')
+      ).trim().toLowerCase();
+      if (retireAnswer === 'y' || retireAnswer === 'yes') {
+        const retired = retireLegacyOffload({ approved: true });
+        console.log(`  retired offload: ${retired.changed ? `archived at ${retired.destination}` : retired.reason}`);
+      }
+    }
+  } else {
+    console.log('  agent integration: skipped (install later with bullswarm integrate install --yes)');
   }
 
   rl.close();

package/src/workflow/runs-cli.js

@@ -4,6 +4,8 @@
 //   bullswarm workflow runs --all                 # list ongoing + historical
 //   bullswarm workflow runs --historical          # only historical
 //   bullswarm workflow runs --name <workflow>     # filter by workflow name
+//   bullswarm workflow runs --all --since 7d      # initiated in the last 7 days
+//   bullswarm workflow runs --all --since yesterday --until today
 //   bullswarm workflow runs --limit N             # cap result count
 //   bullswarm workflow runs show <id>             # dump state + report
 //   bullswarm workflow runs delete <id> --yes     # remove the run directory
@@ -32,29 +34,60 @@ export function cmdRuns(args) {
 export function runsUsage() {
   return `usage:
   bullswarm workflow runs                       # list ongoing runs
-  bullswarm workflow runs [--all | --historical] [--name <workflow>] [--limit N] [--json]
+  bullswarm workflow runs [--all | --historical] [--name <workflow>]
+    [--since <time>] [--until <time>] [--limit N] [--json]
   bullswarm workflow runs show <id>             # <id> = shortId (6 chars) or full runId
-  bullswarm workflow runs delete <id> --yes     # remove the run directory`;
+  bullswarm workflow runs delete <id> --yes     # remove the run directory
+
+Time filters compare the workflow initiation timestamp (startedAt):
+  --since / --started-after / --from   inclusive lower bound
+  --until / --started-before / --to    exclusive upper bound
+Values accept ISO timestamps, local dates, today/yesterday/tomorrow/now,
+or relative durations such as 30m, 24h, 7d, and 2w.`;
 }
 
 function parseRunsFlags(argv) {
   const out = { _positional: [] };
+  const valueFlags = new Map([
+    ['name', 'name'],
+    ['limit', 'limit'],
+    ['since', 'since'],
+    ['started-after', 'since'],
+    ['from', 'since'],
+    ['until', 'until'],
+    ['started-before', 'until'],
+    ['to', 'until'],
+  ]);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--json') out.json = true;
     else if (a === '--all') out.all = true;
     else if (a === '--historical') out.historical = true;
     else if (a === '--yes' || a === '-y') out.yes = true;
-    else if (a === '--name') out.name = argv[++i];
-    else if (a === '--limit') out.limit = Number(argv[++i]);
     else if (a === '--force') out.force = true;
-    else if (a.startsWith('--')) out[a.slice(2)] = true;
+    else if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const key = a.slice(2, eq > 0 ? eq : undefined);
+      const target = valueFlags.get(key);
+      if (target) {
+        const value = eq > 0 ? a.slice(eq + 1) : argv[++i];
+        out[target] = target === 'limit' ? Number(value) : value;
+      } else {
+        out[key] = eq > 0 ? a.slice(eq + 1) : true;
+      }
+    }
     else out._positional.push(a);
   }
   return out;
 }
 
 function runsList(opts) {
+  let initiatedRange;
+  try {
+    initiatedRange = resolveInitiatedRange(opts);
+  } catch (error) {
+    return err(error.message);
+  }
   const all = listRuns(BULLSWARM_DIR());
   let filtered = all;
   if (opts.name) filtered = filtered.filter((r) => r.state?.workflow === opts.name);
@@ -64,10 +97,22 @@ function runsList(opts) {
   } else if (opts.historical) {
     filtered = filtered.filter((r) => !r.ongoing);
   }
+  if (initiatedRange.sinceMs != null) {
+    filtered = filtered.filter((r) => {
+      const startedMs = Date.parse(runStartedAt(r) ?? '');
+      return Number.isFinite(startedMs) && startedMs >= initiatedRange.sinceMs;
+    });
+  }
+  if (initiatedRange.untilMs != null) {
+    filtered = filtered.filter((r) => {
+      const startedMs = Date.parse(runStartedAt(r) ?? '');
+      return Number.isFinite(startedMs) && startedMs < initiatedRange.untilMs;
+    });
+  }
   // Newest first.
   filtered.sort((a, b) => {
-    const ta = a.state?.startedAt ?? '';
-    const tb = b.state?.startedAt ?? '';
+    const ta = runStartedAt(a) ?? '';
+    const tb = runStartedAt(b) ?? '';
     return tb.localeCompare(ta);
   });
   if (opts.limit && opts.limit > 0) filtered = filtered.slice(0, opts.limit);
@@ -77,6 +122,15 @@ function runsList(opts) {
       ongoing: opts.all || !opts.historical,
       historical: opts.all || opts.historical,
       name: opts.name ?? null,
+      initiatedRange: {
+        field: 'startedAt',
+        sinceInclusive: initiatedRange.sinceMs == null
+          ? null
+          : new Date(initiatedRange.sinceMs).toISOString(),
+        untilExclusive: initiatedRange.untilMs == null
+          ? null
+          : new Date(initiatedRange.untilMs).toISOString(),
+      },
       count: filtered.length,
       runs: filtered.map(summarize),
     }, opts);
@@ -96,7 +150,7 @@ function runsList(opts) {
   for (const r of filtered) {
     const wf = r.state?.workflow ?? '?';
     const status = r.state?.status ?? (r.ongoing ? 'running' : 'unknown');
-    const age = humanAge(r.state?.startedAt);
+    const age = humanAge(runStartedAt(r));
     const phases = `${r.state?.steps?.filter((s) => s.ok).length ?? 0}/${r.state?.steps?.length ?? 0}`;
     console.log(
       `${r.ongoing ? '●' : '○'}  ${(r.shortId ?? '------').padEnd(8)} ` +
@@ -167,8 +221,8 @@ function summarize(r) {
     shortId: r.shortId,
     workflow: r.state?.workflow ?? null,
     status: r.state?.status ?? null,
-    startedAt: r.state?.startedAt ?? null,
-    finishedAt: r.state?.finishedAt ?? null,
+    startedAt: runStartedAt(r),
+    finishedAt: r.state?.finishedAt ?? r.report?.finishedAt ?? null,
     ongoing: r.ongoing,
     stepsOk: r.state?.steps?.filter((s) => s.ok).length ?? 0,
     stepsFailed: r.state?.steps?.filter((s) => s.ok === false).length ?? 0,
@@ -177,6 +231,58 @@ function summarize(r) {
   };
 }
 
+function runStartedAt(run) {
+  return run.state?.startedAt ?? run.report?.startedAt ?? null;
+}
+
+function resolveInitiatedRange(opts, nowMs = Date.now()) {
+  const sinceMs = opts.since == null ? null : parseTimeBound(opts.since, nowMs, '--since');
+  const untilMs = opts.until == null ? null : parseTimeBound(opts.until, nowMs, '--until');
+  if (sinceMs != null && untilMs != null && sinceMs >= untilMs) {
+    throw new Error('initiated-time range is empty: --since must be earlier than --until');
+  }
+  return { sinceMs, untilMs };
+}
+
+function parseTimeBound(value, nowMs, flag) {
+  const raw = String(value ?? '').trim();
+  if (!raw) throw new Error(`${flag} requires a time value`);
+  const normalized = raw.toLowerCase();
+
+  if (normalized === 'now') return nowMs;
+  if (['yesterday', 'today', 'tomorrow'].includes(normalized)) {
+    const date = new Date(nowMs);
+    date.setHours(0, 0, 0, 0);
+    if (normalized === 'yesterday') date.setDate(date.getDate() - 1);
+    if (normalized === 'tomorrow') date.setDate(date.getDate() + 1);
+    return date.getTime();
+  }
+
+  const duration = normalized.match(/^(\d+(?:\.\d+)?)(m|h|d|w)$/);
+  if (duration) {
+    const unitMs = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[duration[2]];
+    return nowMs - Number(duration[1]) * unitMs;
+  }
+
+  const localDate = normalized.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (localDate) {
+    const [, year, month, day] = localDate;
+    const date = new Date(Number(year), Number(month) - 1, Number(day));
+    if (date.getFullYear() !== Number(year)
+      || date.getMonth() !== Number(month) - 1
+      || date.getDate() !== Number(day)) {
+      throw new Error(`${flag} has an invalid calendar date: "${raw}"`);
+    }
+    return date.getTime();
+  }
+
+  const parsed = Date.parse(raw);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${flag} has an invalid time: "${raw}"`);
+  }
+  return parsed;
+}
+
 function humanAge(iso) {
   if (!iso) return '—';
   const ms = Date.now() - Date.parse(iso);