@aiwg/cli 2026.8.20 → 2026.8.26

package/bin/aiwg.mjs

@@ -203,13 +203,6 @@ function maybeHandleFastHelp(args) {
   return true;
 }
 
-if (maybeHandleFastVersion(process.argv.slice(2))) {
-  process.exit(0);
-}
-if (maybeHandleFastHelp(process.argv.slice(2))) {
-  process.exit(0);
-}
-
 // Preflight: verify dist/ is built before any of the dynamic imports below
 // try to resolve files that don't exist. Without this, a missing/incomplete
 // dist/ surfaces as a raw `Cannot find module '.../dist/src/.../*.mjs'` from
@@ -240,6 +233,31 @@ function maybeWarnUnbuiltDist() {
 }
 maybeWarnUnbuiltDist();
 
+// Display a cached notice and schedule its refresh before every eligible CLI
+// path, including fast help/version, channel recovery, and later preflight
+// failures. This local-only bootstrap never waits on the registry and failures
+// are deliberately ignored so update advice cannot change command behavior.
+async function runUpdateNotifierBootstrap() {
+  try {
+    const notifierPath = path.join(packageRoot, 'dist', 'src', 'update', 'notifier.mjs');
+    const notifier = await import(pathToFileURL(notifierPath).href);
+    const activePackageRoot = notifier.resolveActivePackageRoot(packageRoot);
+    notifier.maybePrintNotice(activePackageRoot);
+    notifier.scheduleBackgroundCheck(activePackageRoot);
+  } catch {
+    // Best effort: installation/router diagnostics retain authority.
+  }
+}
+
+await runUpdateNotifierBootstrap();
+
+if (maybeHandleFastVersion(process.argv.slice(2))) {
+  process.exit(0);
+}
+if (maybeHandleFastHelp(process.argv.slice(2))) {
+  process.exit(0);
+}
+
 // Mint or inherit an invocation ID before anything else loads. Child processes
 // spawned by handlers (detached update-notifier, aiwg exec, etc.) inherit the
 // parent's ID via `AIWG_INVOCATION_ID` so their JSONL log records correlate
@@ -398,15 +416,6 @@ async function main() {
   // tag every record with it.
   await applyVerbosityFromArgs(args, routerPath);
 
-  // Update notifier: print any pending notice from the previous run's
-  // background check, then schedule the next background check. Both are
-  // non-blocking — the current command never waits on the network.
-  // Honors NO_UPDATE_NOTIFIER, CI=*, and non-TTY stderr.
-  const notifierPath = path.join(activePackageRoot, 'dist', 'src', 'update', 'notifier.mjs');
-  const { scheduleBackgroundCheck, maybePrintNotice } = await import(pathToFileURL(notifierPath).href);
-  maybePrintNotice(activePackageRoot);
-  scheduleBackgroundCheck(activePackageRoot);
-
   // Top-level cancellation controller. SIGINT / SIGTERM flip it, long-running
   // handlers plumb ctx.signal through fetches and loops so Ctrl-C cancels
   // in-flight work cleanly instead of leaving orphaned sockets and children.

package/dist/src/api/index.d.ts

@@ -9,6 +9,7 @@ export { run } from '../cli/router.js';
 export * from '../resources/index.js';
 export * from '../sessions/index.js';
 export * from '../memory/index.js';
+export * from '../storage/index.js';
 export * from '../security/threat-assessment-config.js';
 export * from '../security/artifact-verifier.js';
 export * from '../security/artifact-attestation.js';

package/dist/src/api/index.js

@@ -9,6 +9,7 @@ export { run } from '../cli/router.js';
 export * from '../resources/index.js';
 export * from '../sessions/index.js';
 export * from '../memory/index.js';
+export * from '../storage/index.js';
 export * from '../security/threat-assessment-config.js';
 export * from '../security/artifact-verifier.js';
 export * from '../security/artifact-attestation.js';

package/dist/src/cli/handlers/artifact-verify.js

@@ -102,6 +102,9 @@ export const artifactVerifyHandler = {
     description: 'Verify cross-asset DSSE provenance and manage trust roots',
     category: 'utility',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage() };
+    },
     async execute(ctx) {
         if (ctx.args.includes('--help') || ctx.args.includes('-h') || ctx.args.length === 0)
             return { exitCode: 0, message: usage() };

package/dist/src/cli/handlers/refresh.js

@@ -10,7 +10,7 @@
  *
  * @implements @agentic/code/frameworks/sdlc-complete/rules/self-maintenance.md
  * @source @src/cli/router.ts
- * @issue #482, #557, #694
+ * @issue #173, #174, #482, #557, #694
  */
 import { promises as fs } from 'fs';
 import path from 'path';
@@ -151,6 +151,30 @@ export function collectModelDeployArgs(args) {
     }
     return forwarded;
 }
+const REFRESH_HELP = `Usage: aiwg refresh [options]
+
+Update AIWG, re-deploy installed frameworks, and run health verification.
+
+Options:
+  --dry-run                 Preview changes without updating or deploying
+  --quiet                   Suppress progress output
+  --skip-update             Skip the installation update
+  --packages-only           Refresh remote packages only
+  --provider <name>         Override provider auto-detection
+  --channel <name>          Select the update channel (stable or main)
+  --frameworks <list>       Re-deploy a comma-separated installed subset
+  --model <name>            Override all deployed agent model tiers
+  --reasoning-model <name>  Override the reasoning model tier
+  --coding-model <name>     Override the coding model tier
+  --efficiency-model <name> Override the efficiency model tier
+  --filter <pattern>        Limit model deployment by agent name
+  --filter-role <role>      Limit model deployment by role
+  --model-tier <tier>       Limit model deployment by tier
+  --save                    Save model overrides to the project
+  --save-user               Save model overrides to user configuration
+  -h, --help                Show this help without running refresh
+
+Alias: aiwg sync (deprecated)`;
 /**
  * Refresh command handler (formerly sync)
  */
@@ -160,6 +184,9 @@ export const refreshHandler = {
     description: 'Refresh AIWG to latest version and re-deploy installed frameworks',
     category: 'maintenance',
     aliases: ['--refresh', 'sync', '--sync'],
+    async help() {
+        return { exitCode: 0, message: REFRESH_HELP, rawOutput: true };
+    },
     async execute(ctx) {
         const dryRun = hasFlag(ctx.args, '--dry-run');
         const quiet = hasFlag(ctx.args, '--quiet');
@@ -451,6 +478,10 @@ export const refreshHandler = {
             if (dryRun) {
                 ui.info('Dry run complete — no changes made');
             }
+            else if (updateFailure) {
+                ui.warn(`Refresh completed with installation update failure (exit ${updateFailure.exitCode}); ` +
+                    're-deployment continued, but AIWG may still be on the previous version.');
+            }
             else {
                 ui.success('Refresh complete');
             }
@@ -459,7 +490,11 @@ export const refreshHandler = {
         // Quiet mode: JSON output
         if (quiet) {
             const output = JSON.stringify({
-                status: dryRun ? 'dry-run' : 'refreshed',
+                status: dryRun
+                    ? 'dry-run'
+                    : updateFailure
+                        ? 'refreshed-with-update-failure'
+                        : 'refreshed',
                 provider: detectedProvider,
                 frameworks,
                 skipUpdate,

package/dist/src/cli/handlers/subcommands.js

@@ -1139,34 +1139,40 @@ export const pluginStatusHandler = {
  *
  * Delegates to tools/plugin/package-plugins.mjs
  */
+function packagePluginHelp() {
+    return {
+        exitCode: 0,
+        message: [
+            "aiwg package-plugin — package a project-local or built-in marketplace wrapper",
+            "",
+            "Usage:",
+            "  aiwg package-plugin <name> [--source <path>] [--output <path>] [--provider <name>] [--clean] [--dry-run]",
+            "  aiwg package-plugin --plugin <name> [options]  # compatibility form",
+            "",
+            "Options:",
+            "  --source <path>    explicit project-local wrapper source (must stay inside the project)",
+            "  --output <path>    standalone archive output (default: dist/plugins)",
+            "  --provider <name>  claude, codex, or all for standalone wrappers; built-ins retain all formats",
+            "  --clean            clean generated plugin output before packaging",
+            "  --dry-run, -n      preview without writing",
+            "  --help, -h         show this help",
+            "",
+            "Project-local wrappers are discovered under .aiwg/plugins and packaged as deterministic archives.",
+        ].join("\n"),
+    };
+}
 export const packagePluginHandler = {
     id: "package-plugin",
     name: "Package Plugin",
     description: "Package a plugin for distribution",
     category: "plugin",
     aliases: ["-package-plugin", "--package-plugin"],
+    async help() {
+        return packagePluginHelp();
+    },
     async execute(ctx) {
         if (ctx.args.includes("--help") || ctx.args.includes("-h")) {
-            return {
-                exitCode: 0,
-                message: [
-                    "aiwg package-plugin — package a project-local or built-in marketplace wrapper",
-                    "",
-                    "Usage:",
-                    "  aiwg package-plugin <name> [--source <path>] [--output <path>] [--provider <name>] [--clean] [--dry-run]",
-                    "  aiwg package-plugin --plugin <name> [options]  # compatibility form",
-                    "",
-                    "Options:",
-                    "  --source <path>    explicit project-local wrapper source (must stay inside the project)",
-                    "  --output <path>    standalone archive output (default: dist/plugins)",
-                    "  --provider <name>  claude, codex, or all for standalone wrappers; built-ins retain all formats",
-                    "  --clean            clean generated plugin output before packaging",
-                    "  --dry-run, -n      preview without writing",
-                    "  --help, -h         show this help",
-                    "",
-                    "Project-local wrappers are discovered under .aiwg/plugins and packaged as deterministic archives.",
-                ].join("\n"),
-            };
+            return packagePluginHelp();
         }
         const hasExplicitPlugin = ctx.args.includes("--plugin") || ctx.args.includes("-p");
         const positional = ctx.args[0] && !ctx.args[0].startsWith("-")

package/dist/src/cli/handlers/utilities.js

@@ -466,6 +466,9 @@ export const doctorHandler = {
     description: 'Run health diagnostics',
     category: 'maintenance',
     aliases: ['-doctor', '--doctor'],
+    async help() {
+        return { exitCode: 0, message: DOCTOR_HELP, rawOutput: true };
+    },
     async execute(ctx) {
         if (ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: DOCTOR_HELP, rawOutput: true };

package/dist/src/cli/router.js

@@ -10,6 +10,7 @@
  * @tests @test/unit/cli/router.test.ts
  * @issue #33
  * @issue #58
+ * @issue #174
  */
 import { loadRegistry } from '../extensions/loader.js';
 import { getFrameworkRoot } from '../channel/manager.mjs';
@@ -134,6 +135,32 @@ export async function run(args, options = {}) {
         ui.error(`No handler found for command: ${commandId}`);
         process.exit(1);
     }
+    // Help must be intercepted before hooks and the normal handler path. Some
+    // commands mutate project or installation state, so passing an unrecognised
+    // help flag through to execute() is unsafe (#174).
+    if (commandArgs.includes('--help') || commandArgs.includes('-h')) {
+        const ctx = await buildContext(commandArgs, args, options);
+        if (handler.help) {
+            const result = await handler.help(ctx);
+            if (result.message) {
+                if (result.rawOutput) {
+                    process.stdout.write(result.message.endsWith('\n') ? result.message : `${result.message}\n`);
+                }
+                else if (result.exitCode !== 0) {
+                    ui.error(result.message);
+                }
+                else {
+                    ui.info(result.message);
+                }
+            }
+            if (result.exitCode !== 0)
+                process.exit(result.exitCode);
+        }
+        else {
+            ui.info(`No detailed help for \`aiwg ${commandId}\`. Run \`aiwg help\` for the command overview.`);
+        }
+        return;
+    }
     // Build context for handler and hooks
     const ctx = await buildContext(commandArgs, args, options);
     // Build hook context

package/dist/src/features/catalog.js

@@ -42,6 +42,17 @@ export const FEATURE_CATALOG = [
         ],
         cost: '~5 MB — native compile via node-gyp',
     },
+    {
+        name: 'postgres',
+        description: 'Advanced direct PostgreSQL canonical-storage backend',
+        packages: ['pg'],
+        packageSpecs: { pg: '8.23.0' },
+        enables: [
+            'aiwg.storage-backend/v1 direct PostgreSQL persistence',
+            'transactional migration batches, snapshots, cursors, and tombstones',
+        ],
+        cost: '~1 MB — pure JavaScript PostgreSQL client',
+    },
     {
         name: 'pty',
         description: 'PTY bridge for daemon — pass-through interactive TUIs (Claude Code, Codex, etc.)',

package/dist/src/installation/manager-command.mjs

@@ -21,11 +21,20 @@ export function resolveManagerCommand(file, args, options = {}) {
   return {
     file: commandInterpreter,
     args: ['/d', '/s', '/c', command],
+    // The payload above already contains cmd.exe-native quoting. Instruct
+    // Node not to apply MSVCRT escaping to those embedded quotes (#173).
+    windowsVerbatimArguments: true,
   };
 }
 
 export function executeManagerCommand(file, args, options = {}) {
   const invocation = resolveManagerCommand(file, args, options);
   const execute = options.execute ?? execFileSync;
-  return execute(invocation.file, invocation.args, options.execOptions ?? { stdio: 'inherit' });
+  const execOptions = options.execOptions
+    ? { ...options.execOptions }
+    : { stdio: 'inherit' };
+  if (invocation.windowsVerbatimArguments === true) {
+    execOptions.windowsVerbatimArguments = true;
+  }
+  return execute(invocation.file, invocation.args, execOptions);
 }

package/dist/src/storage/backend-contract.js

@@ -43,8 +43,17 @@ export const STORAGE_BACKEND_MATRIX = {
     sqlite: descriptor('sqlite', 'supported', [...BASELINE, 'atomic-batch', 'consistent-snapshot', 'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination', 'backup', 'restore'], 'wal', 'single-host', 'serializable', 'regenerable-index'),
     'fortemi-core-static': descriptor('fortemi-core-static', 'supported', ['read', 'filtered-query', 'recursive-traversal', 'set-operations'], 'filesystem', 'single-host', 'snapshot', 'static-cache'),
     'fortemi-server': descriptor('fortemi-server', 'alpha', [...BASELINE, 'filtered-query', 'health', 'tls', 'tenant-isolation'], 'replicated', 'remote-service', 'none', 'remote-persistence'),
-    'postgres-direct': descriptor('postgres-direct', 'advanced', [], 'replicated', 'remote-service', 'none', 'canonical'),
-    'postgres-postgrest': descriptor('postgres-postgrest', 'advanced', [], 'replicated', 'remote-service', 'none', 'canonical'),
+    'postgres-direct': descriptor('postgres-direct', 'advanced', [
+        ...BASELINE, 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+        'tombstones', 'idempotency-keys', 'recursive-traversal', 'set-operations',
+        'filtered-query', 'cursor-pagination', 'health', 'readiness', 'telemetry',
+        'tenant-isolation', 'tls',
+    ], 'replicated', 'remote-service', 'serializable', 'canonical'),
+    'postgres-postgrest': descriptor('postgres-postgrest', 'advanced', [
+        ...BASELINE, 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+        'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination',
+        'health', 'readiness', 'tenant-isolation', 'tls',
+    ], 'replicated', 'remote-service', 'serializable', 'canonical'),
     mysql: descriptor('mysql', 'deferred', [], 'replicated', 'remote-service', 'none', 'canonical'),
 };
 function descriptor(backend, maturity, capabilities, durability, availability, isolation, dataClass) {

package/dist/src/storage/backends/postgres-schema.js

@@ -0,0 +1,144 @@
+export const POSTGRES_SCHEMA_VERSION = 1;
+export const POSTGRES_SCHEMA_V1_SQL = `
+CREATE TABLE IF NOT EXISTS aiwg_storage_schema (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  schema_version integer NOT NULL
+);
+INSERT INTO aiwg_storage_schema(singleton, schema_version)
+VALUES (true, 1) ON CONFLICT (singleton) DO NOTHING;
+CREATE TABLE IF NOT EXISTS aiwg_storage_records (
+  tenant text NOT NULL,
+  subsystem text NOT NULL,
+  path text NOT NULL,
+  source_revision text NOT NULL,
+  digest text NOT NULL,
+  value jsonb,
+  tombstone boolean NOT NULL DEFAULT false,
+  deleted_at timestamptz,
+  delete_reason text,
+  idempotency_key text NOT NULL,
+  change_seq bigserial NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  PRIMARY KEY (tenant, subsystem, path),
+  UNIQUE (tenant, subsystem, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS aiwg_storage_records_change
+  ON aiwg_storage_records(tenant, subsystem, change_seq, path);
+CREATE TABLE IF NOT EXISTS aiwg_storage_batch_receipts (
+  tenant text NOT NULL,
+  subsystem text NOT NULL,
+  batch_id uuid NOT NULL,
+  payload_digest text NOT NULL,
+  high_water_mark bigint NOT NULL,
+  receipt jsonb NOT NULL,
+  committed_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  PRIMARY KEY (tenant, subsystem, batch_id)
+);
+CREATE TABLE IF NOT EXISTS aiwg_storage_edges (
+  tenant text NOT NULL,
+  subsystem text NOT NULL,
+  source_path text NOT NULL,
+  target_path text NOT NULL,
+  edge_type text NOT NULL,
+  PRIMARY KEY (tenant, subsystem, source_path, target_path, edge_type)
+);
+CREATE INDEX IF NOT EXISTS aiwg_storage_edges_target
+  ON aiwg_storage_edges(tenant, subsystem, target_path, edge_type);
+`;
+const POSTGREST_FUNCTIONS = [
+    'aiwg_reload_schema_v1()',
+    'aiwg_health_v1(text,text)',
+    'aiwg_changes_v1(text,text,bigint,integer)',
+    'aiwg_snapshot_v1(text,text,integer)',
+    'aiwg_query_records_v1(text,text,jsonb,text,integer,boolean)',
+    'aiwg_get_record_v1(text,text,text)',
+    'aiwg_commit_batch_v1(text,text,uuid,text,jsonb)',
+    'aiwg_record_v1(aiwg_storage_records)',
+];
+export async function inspectPostgresSchema(client) {
+    const exists = await client.query("SELECT to_regclass('public.aiwg_storage_schema') IS NOT NULL AS exists");
+    if (!exists.rows[0]?.exists)
+        return { version: 0, records: 0, receipts: 0, edges: 0 };
+    const result = await client.query(`
+    SELECT schema_version,
+      (SELECT count(*) FROM aiwg_storage_records) AS records,
+      (SELECT count(*) FROM aiwg_storage_batch_receipts) AS receipts,
+      (SELECT count(*) FROM aiwg_storage_edges) AS edges
+    FROM aiwg_storage_schema WHERE singleton=true`);
+    const row = result.rows[0];
+    if (Number(row?.schema_version) !== 1)
+        throw new Error(`unsupported PostgreSQL storage schema ${String(row?.schema_version)}`);
+    return { version: 1, records: Number(row.records), receipts: Number(row.receipts), edges: Number(row.edges) };
+}
+/** Upgrade an empty database to v1 under a dedicated migration-role connection. */
+export async function upgradePostgresSchemaV1(client) {
+    await client.query('BEGIN');
+    try {
+        await client.query("SELECT pg_advisory_xact_lock(hashtextextended('aiwg-storage-schema',0))");
+        const before = await inspectPostgresSchema(client);
+        if (before.version === 1) {
+            await client.query('COMMIT');
+            return before;
+        }
+        await client.query(POSTGRES_SCHEMA_V1_SQL);
+        const after = await inspectPostgresSchema(client);
+        if (after.version !== 1)
+            throw new Error('PostgreSQL schema upgrade did not reach v1');
+        await client.query('COMMIT');
+        return after;
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { /* preserve upgrade error */ }
+        throw error;
+    }
+}
+/**
+ * Roll v1 back to an empty schema. This is intentionally impossible without
+ * exact version and observed-count acknowledgements from a prior inspection.
+ */
+export async function rollbackPostgresSchemaV1(client, approval) {
+    if (approval.expectedVersion !== 1 || approval.allowDataLoss !== true)
+        throw new Error('explicit v1 data-loss approval is required');
+    await client.query('BEGIN');
+    try {
+        await client.query("SELECT pg_advisory_xact_lock(hashtextextended('aiwg-storage-schema',0))");
+        const before = await inspectPostgresSchema(client);
+        const observed = { records: before.records, receipts: before.receipts, edges: before.edges };
+        if (before.version !== 1 || JSON.stringify(observed) !== JSON.stringify(approval.expectedCounts)) {
+            throw new Error('schema rollback approval does not match current version/counts');
+        }
+        for (const signature of POSTGREST_FUNCTIONS)
+            await client.query(`DROP FUNCTION IF EXISTS ${signature}`);
+        await client.query('DROP TABLE aiwg_storage_edges, aiwg_storage_batch_receipts, aiwg_storage_records, aiwg_storage_schema');
+        const after = await inspectPostgresSchema(client);
+        if (after.version !== 0)
+            throw new Error('PostgreSQL schema rollback did not reach v0');
+        await client.query('COMMIT');
+        return after;
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { /* preserve rollback error */ }
+        throw error;
+    }
+}
+export function postgresLeastPrivilegeSql(runtimeRole) {
+    const role = quoteIdentifier(runtimeRole);
+    return `REVOKE ALL ON aiwg_storage_records, aiwg_storage_batch_receipts, aiwg_storage_edges FROM PUBLIC;
+REVOKE ALL ON aiwg_storage_schema FROM PUBLIC;
+GRANT USAGE ON SCHEMA public TO ${role};
+GRANT SELECT, INSERT, UPDATE, DELETE ON aiwg_storage_records, aiwg_storage_batch_receipts, aiwg_storage_edges TO ${role};
+GRANT SELECT ON aiwg_storage_schema TO ${role};
+GRANT USAGE, SELECT ON SEQUENCE aiwg_storage_records_change_seq_seq TO ${role};`;
+}
+function quoteIdentifier(value) {
+    if (!value || value.length > 63 || /[\u0000-\u001f]/.test(value))
+        throw new Error('runtime role must be a printable PostgreSQL identifier up to 63 characters');
+    return `"${value.replaceAll('"', '""')}"`;
+}
+//# sourceMappingURL=postgres-schema.js.map