@aiwg/cli 2026.8.25 → 2026.8.26

package/dist/src/storage/backends/postgrest.js

@@ -0,0 +1,346 @@
+import { STORAGE_BACKEND_CONTRACT } from '../backend-contract.js';
+import { postgresBatchId, postgresPayloadDigest } from './postgres.js';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576;
+const DEFAULT_PAGE_SIZE = 1000;
+export class PostgrestBackendError extends Error {
+    code;
+    retryable;
+    retryAfterMs;
+    constructor(code, message, retryable = false, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'PostgrestBackendError';
+    }
+}
+/** PostgreSQL accessMode=postgrest; not a separate storage engine. */
+export class PostgrestStorageBackend {
+    options;
+    descriptor = {
+        contract: STORAGE_BACKEND_CONTRACT,
+        backend: 'postgres-postgrest',
+        implementationVersion: '1.0.0',
+        schemaVersion: '1',
+        maturity: 'advanced',
+        capabilities: [
+            'read', 'atomic-batch', 'consistent-snapshot', 'change-cursor',
+            'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination',
+            'health', 'readiness', 'tenant-isolation', 'subsystem-isolation', 'tls',
+        ],
+        durability: 'replicated',
+        availability: 'remote-service',
+        isolation: 'serializable',
+        dataClass: 'canonical',
+    };
+    identity;
+    baseUrl;
+    fetchImpl;
+    timeoutMs;
+    maxPayloadBytes;
+    maxResponseBytes;
+    maxBatchSize;
+    maxPageSize;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl)
+            throw new PostgrestBackendError('AIWG_POSTGREST_FETCH_UNAVAILABLE', 'fetch is unavailable');
+        this.timeoutMs = bounded(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1, 600_000, 'timeoutMs');
+        this.maxPayloadBytes = bounded(options.maxPayloadBytes, DEFAULT_MAX_PAYLOAD_BYTES, 1024, 16_777_216, 'maxPayloadBytes');
+        this.maxResponseBytes = bounded(options.maxResponseBytes, DEFAULT_MAX_PAYLOAD_BYTES, 1024, 16_777_216, 'maxResponseBytes');
+        this.maxBatchSize = bounded(options.maxBatchSize, DEFAULT_PAGE_SIZE, 1, 10_000, 'maxBatchSize');
+        this.maxPageSize = bounded(options.maxPageSize, DEFAULT_PAGE_SIZE, 1, 10_000, 'maxPageSize');
+        this.identity = {
+            backend: 'postgres-postgrest', instance: options.instance ?? this.baseUrl,
+            tenant: options.tenant, subsystem: options.subsystem, schemaVersion: '1',
+        };
+    }
+    async init() {
+        const health = await this.health();
+        if (!health.ready || health.schemaVersion !== '1') {
+            throw new PostgrestBackendError('AIWG_POSTGREST_SCHEMA_UNAVAILABLE', 'PostgREST schema/RPC contract v1 is unavailable');
+        }
+    }
+    async commitBatch(mutations) {
+        if (mutations.length === 0)
+            throw new PostgrestBackendError('AIWG_POSTGREST_EMPTY_BATCH', 'batch must contain at least one mutation');
+        if (mutations.length > this.maxBatchSize)
+            throw new PostgrestBackendError('AIWG_POSTGREST_BATCH_TOO_LARGE', `batch exceeds ${this.maxBatchSize} mutation ceiling`);
+        for (const mutation of mutations)
+            this.assertMutationIdentity(mutation);
+        return this.rpc('aiwg_commit_batch_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_batch_id: postgresBatchId(mutations),
+            p_payload_digest: postgresPayloadDigest(mutations),
+            p_mutations: mutations,
+        }, 'return=representation');
+    }
+    async get(path) {
+        return this.rpc('aiwg_get_record_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_path: path,
+        });
+    }
+    async readAll() {
+        const records = [];
+        let cursor;
+        do {
+            const page = await this.query({}, this.maxPageSize, cursor, true);
+            records.push(...page.records);
+            cursor = page.nextCursor;
+        } while (cursor);
+        return records;
+    }
+    async query(filters, limit = this.maxPageSize, cursor, includeTombstones = false) {
+        const boundedLimit = bounded(limit, this.maxPageSize, 1, this.maxPageSize, 'limit');
+        return this.rpc('aiwg_query_records_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_filters: filters,
+            p_after_path: cursor ?? null,
+            p_limit: boundedLimit,
+            p_include_tombstones: includeTombstones,
+        });
+    }
+    async snapshot() {
+        const response = await this.rpc('aiwg_snapshot_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_limit: this.maxPageSize,
+        });
+        return {
+            id: response.snapshot_id,
+            highWaterMark: response.high_water_mark,
+            cursor: response.high_water_mark,
+            records: response.records,
+        };
+    }
+    async changes(cursor) {
+        if (cursor !== undefined && !/^\d+$/.test(cursor)) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_CURSOR_INVALID', 'change cursor must be an unsigned integer');
+        }
+        const response = await this.rpc('aiwg_changes_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+            p_after_cursor: cursor ?? '0',
+            p_limit: this.maxPageSize,
+        });
+        return {
+            records: response.records,
+            highWaterMark: response.high_water_mark,
+            ...(response.next_cursor ? { nextCursor: response.next_cursor } : {}),
+        };
+    }
+    async reloadSchemaCache() {
+        await this.rpc('aiwg_reload_schema_v1', {});
+    }
+    async health() {
+        return this.rpc('aiwg_health_v1', {
+            p_tenant: this.options.tenant,
+            p_subsystem: this.options.subsystem,
+        });
+    }
+    /** Receipt-less native JSON bulk upsert for controlled bootstrap only. */
+    async bulkBootstrapJson(rows) {
+        this.assertBootstrapCount(rows.length);
+        for (const row of rows)
+            this.assertBootstrapIdentity(row.tenant, row.subsystem);
+        return this.request('/aiwg_storage_records?on_conflict=tenant%2Csubsystem%2Cpath', {
+            method: 'POST', body: rows, prefer: 'resolution=merge-duplicates,return=representation',
+        });
+    }
+    /** Receipt-less native CSV bulk upsert for controlled bootstrap only. */
+    async bulkBootstrapCsv(csv) {
+        const parsed = parseCsv(csv);
+        const required = ['tenant', 'subsystem', 'path', 'source_revision', 'digest', 'value', 'tombstone', 'idempotency_key'];
+        for (const column of required) {
+            if (!parsed.header.includes(column))
+                throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', `CSV header is missing ${column}`);
+        }
+        this.assertBootstrapCount(parsed.rows.length);
+        const tenantIndex = parsed.header.indexOf('tenant');
+        const subsystemIndex = parsed.header.indexOf('subsystem');
+        for (const row of parsed.rows)
+            this.assertBootstrapIdentity(row[tenantIndex] ?? '', row[subsystemIndex] ?? '');
+        return this.request('/aiwg_storage_records?on_conflict=tenant%2Csubsystem%2Cpath', {
+            method: 'POST', rawBody: csv, contentType: 'text/csv',
+            prefer: 'resolution=merge-duplicates,return=representation',
+        });
+    }
+    async rpc(name, body, prefer) {
+        return this.request(`/rpc/${name}`, { method: 'POST', body, ...(prefer ? { prefer } : {}) });
+    }
+    async request(pathname, options = {}) {
+        const body = options.rawBody ?? (options.body === undefined ? undefined : JSON.stringify(options.body));
+        if (body && Buffer.byteLength(body) > this.maxPayloadBytes) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_PAYLOAD_TOO_LARGE', `request exceeds ${this.maxPayloadBytes} byte ceiling`);
+        }
+        const headers = { Accept: 'application/json' };
+        if (body)
+            headers['Content-Type'] = options.contentType ?? 'application/json';
+        if (options.prefer)
+            headers.Prefer = options.prefer;
+        const authorization = this.authorization();
+        if (authorization)
+            headers.Authorization = authorization;
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${pathname}`, {
+                method: options.method ?? 'GET', headers, body,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_TRANSPORT_FAILED', error instanceof Error ? error.message : String(error), true);
+        }
+        if (response.status === 204)
+            return undefined;
+        const declaredLength = Number(response.headers.get('content-length') ?? '0');
+        if (declaredLength > this.maxResponseBytes) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_RESPONSE_TOO_LARGE', `response exceeds ${this.maxResponseBytes} byte ceiling`);
+        }
+        const responseBody = await response.text();
+        if (Buffer.byteLength(responseBody) > this.maxResponseBytes) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_RESPONSE_TOO_LARGE', `response exceeds ${this.maxResponseBytes} byte ceiling`);
+        }
+        if (!response.ok) {
+            const databaseError = parseDatabaseError(responseBody);
+            const retryable = response.status === 408 || response.status === 425 || response.status === 429 ||
+                response.status >= 500 || isRetryableDatabaseCode(databaseError.databaseCode);
+            const exposedCode = databaseError.message?.startsWith('AIWG_')
+                ? databaseError.message
+                : retryable ? 'AIWG_POSTGREST_RETRYABLE' : 'AIWG_POSTGREST_REQUEST_FAILED';
+            throw new PostgrestBackendError(exposedCode, `PostgREST request failed with HTTP ${response.status}${databaseError.databaseCode ? ` (database ${databaseError.databaseCode})` : ''}`, retryable, parseRetryAfter(response.headers.get('retry-after')));
+        }
+        try {
+            return JSON.parse(responseBody);
+        }
+        catch {
+            throw new PostgrestBackendError('AIWG_POSTGREST_RESPONSE_INVALID', 'PostgREST returned invalid JSON');
+        }
+    }
+    authorization() {
+        if (!this.options.authorizationEnv)
+            return undefined;
+        const value = process.env[this.options.authorizationEnv];
+        if (!value)
+            throw new PostgrestBackendError('AIWG_POSTGREST_CREDENTIAL_UNAVAILABLE', `authorization locator ${this.options.authorizationEnv} is not set`);
+        return value;
+    }
+    assertMutationIdentity(mutation) {
+        if (mutation.record.identity.tenant !== this.options.tenant || mutation.record.identity.subsystem !== this.options.subsystem) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_IDENTITY_MISMATCH', 'mutation identity is outside this backend tenant/subsystem');
+        }
+    }
+    assertBootstrapCount(count) {
+        if (count < 1)
+            throw new PostgrestBackendError('AIWG_POSTGREST_EMPTY_BATCH', 'bootstrap batch must contain at least one row');
+        if (count > this.maxBatchSize)
+            throw new PostgrestBackendError('AIWG_POSTGREST_BATCH_TOO_LARGE', `batch exceeds ${this.maxBatchSize} row ceiling`);
+    }
+    assertBootstrapIdentity(tenant, subsystem) {
+        if (tenant !== this.options.tenant || subsystem !== this.options.subsystem) {
+            throw new PostgrestBackendError('AIWG_POSTGREST_IDENTITY_MISMATCH', 'bootstrap row is outside this backend tenant/subsystem');
+        }
+    }
+}
+function parseCsv(input) {
+    const output = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const character = input[index];
+        if (character === '"') {
+            if (quoted && input[index + 1] === '"') {
+                field += '"';
+                index += 1;
+            }
+            else
+                quoted = !quoted;
+        }
+        else if (character === ',' && !quoted) {
+            row.push(field);
+            field = '';
+        }
+        else if ((character === '\n' || character === '\r') && !quoted) {
+            if (character === '\r' && input[index + 1] === '\n')
+                index += 1;
+            row.push(field);
+            field = '';
+            if (row.some(value => value.length > 0))
+                output.push(row);
+            row = [];
+        }
+        else
+            field += character;
+    }
+    if (quoted)
+        throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', 'CSV contains an unterminated quoted field');
+    row.push(field);
+    if (row.some(value => value.length > 0))
+        output.push(row);
+    const header = output.shift();
+    if (!header)
+        throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', 'CSV must contain a header');
+    for (const candidate of output) {
+        if (candidate.length !== header.length)
+            throw new PostgrestBackendError('AIWG_POSTGREST_CSV_INVALID', 'CSV row width does not match header');
+    }
+    return { header, rows: output };
+}
+function parseDatabaseError(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return {
+            ...(typeof parsed.code === 'string' ? { databaseCode: parsed.code } : {}),
+            ...(typeof parsed.message === 'string' ? { message: parsed.message } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function isRetryableDatabaseCode(code) {
+    return Boolean(code && (code === '40001' || code === '40P01' || code === '55P03' || code === '57014' || code.startsWith('08')));
+}
+function normalizeBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new PostgrestBackendError('AIWG_POSTGREST_URL_INVALID', 'baseUrl must be an absolute URL');
+    }
+    const loopback = ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw new PostgrestBackendError('AIWG_POSTGREST_TLS_REQUIRED', 'PostgREST requires HTTPS except on explicit loopback development endpoints');
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new PostgrestBackendError('AIWG_POSTGREST_URL_SECRET_FORBIDDEN', 'baseUrl cannot contain credentials, query parameters, or fragments');
+    }
+    return url.toString().replace(/\/$/, '');
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Math.min(Number(value) * 1000, 60_000);
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return undefined;
+    return Math.max(0, Math.min(timestamp - Date.now(), 60_000));
+}
+function bounded(value, fallback, min, max, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
+        throw new PostgrestBackendError('AIWG_POSTGREST_OPTION_INVALID', `${label} must be an integer from ${min} through ${max}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=postgrest.js.map

package/dist/src/storage/index.js

@@ -23,6 +23,11 @@ export { LogseqAdapter } from './backends/logseq.js';
 export { FortemiAdapter } from './backends/fortemi.js';
 export { STORAGE_BACKEND_CONTRACT, STORAGE_BACKEND_MATRIX, StorageCapabilityError, negotiateStorageCapabilities, } from './backend-contract.js';
 export { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, StorageMigrationCoordinator, approvalDigest, digestRecords, validateManifest, } from './migration-protocol.js';
+export { PostgresStorageBackend, PostgresBackendError, } from './backends/postgres.js';
+export { POSTGRES_SCHEMA_VERSION, POSTGRES_SCHEMA_V1_SQL, inspectPostgresSchema, upgradePostgresSchemaV1, rollbackPostgresSchemaV1, postgresLeastPrivilegeSql, } from './backends/postgres-schema.js';
+export { PostgrestStorageBackend, PostgrestBackendError, } from './backends/postgrest.js';
+export { POSTGREST_SCHEMA_V1_SQL, installPostgrestSchemaV1, postgrestLeastPrivilegeSql } from './backends/postgrest-schema.js';
+export { STORAGE_QUALIFICATION_REPORT, StorageQualificationError, qualifyStorageBackend, verifyExactRecords, assertCurrentStorageEvidence, } from './qualification.js';
 let state = null;
 /**
  * Initialize or reset the registry for a given project root. Most

package/dist/src/storage/qualification.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { digestRecords } from './migration-protocol.js';
+export const STORAGE_QUALIFICATION_REPORT = 'aiwg.storage-qualification/v1';
+/**
+ * Evidence-producing common gate. Correctness is evaluated before latency is
+ * reported, so an incomplete or corrupt run can never become a benchmark.
+ */
+export async function qualifyStorageBackend(endpoint, options) {
+    if (options.records.length !== options.scope.declaredRecords) {
+        throw new Error('declared record scope does not match the qualification corpus');
+    }
+    const now = options.now ?? (() => new Date());
+    const startedAt = now().toISOString();
+    const cpuBefore = process.cpuUsage();
+    const rssBefore = process.memoryUsage().rss;
+    const start = performance.now();
+    const latencies = [];
+    const sideEffects = [];
+    let errors = 0;
+    let retries = 0;
+    const maxRetries = bounded(options.maxRetries, 5, 0, 20, 'maxRetries');
+    const baseBackoffMs = bounded(options.baseBackoffMs, 2, 0, 60_000, 'baseBackoffMs');
+    const batches = distribute(options.records, options.scope.writers);
+    await Promise.all(batches.map(async (records, writer) => {
+        for (const record of records) {
+            const mutation = mutationFor(record, `qualification:${writer}:${record.identity.path}:${record.sourceRevision}`);
+            const operationStart = performance.now();
+            let receipt;
+            let replayed = false;
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    receipt = await endpoint.commitBatch([mutation]);
+                    break;
+                }
+                catch (error) {
+                    errors += 1;
+                    if (!isRetryable(error) || attempt >= maxRetries) {
+                        sideEffects.push({ operation: `write:${record.identity.path}`, outcome: 'failed' });
+                        throw error;
+                    }
+                    retries += 1;
+                    replayed = true;
+                    if (baseBackoffMs > 0)
+                        await new Promise(resolve => setTimeout(resolve, baseBackoffMs * 2 ** attempt));
+                }
+            }
+            latencies.push(performance.now() - operationStart);
+            sideEffects.push({ operation: `write:${record.identity.path}`, outcome: replayed ? 'replayed' : 'committed', batchId: receipt.batchId });
+        }
+    }));
+    const expectedDigest = digestRecords(options.records);
+    const observed = [...await endpoint.readAll()];
+    const verification = verifyExactRecords(options.records, observed);
+    const durationMs = Math.max(performance.now() - start, 0.001);
+    const cpu = process.cpuUsage(cpuBefore);
+    const supplied = options.resourceObservation?.() ?? {};
+    const operations = options.records.length + options.scope.readers;
+    const report = {
+        schemaVersion: STORAGE_QUALIFICATION_REPORT,
+        runId: createHash('sha256').update(`${options.scope.commit}\0${options.scope.backend}\0${startedAt}`).digest('hex'),
+        startedAt,
+        completedAt: now().toISOString(),
+        scope: { ...options.scope, observedRecords: observed.length },
+        verification: { ...verification, expectedDigest, observedDigest: digestRecords(observed) },
+        latencyMs: percentiles(latencies),
+        throughputPerSecond: operations / (durationMs / 1000),
+        errors,
+        retries,
+        errorRate: errors / Math.max(operations, 1),
+        retryRate: retries / Math.max(operations, 1),
+        resources: {
+            cpuUserMicros: cpu.user, cpuSystemMicros: cpu.system,
+            rssBytes: Math.max(process.memoryUsage().rss, rssBefore),
+            ...supplied,
+        },
+        sideEffects: sideEffects.sort((a, b) => a.operation.localeCompare(b.operation)),
+    };
+    if (!report.verification.valid)
+        throw new StorageQualificationError('AIWG_STORAGE_QUALIFICATION_PARITY_FAILED', report);
+    return report;
+}
+export class StorageQualificationError extends Error {
+    code;
+    report;
+    constructor(code, report) {
+        super(`${code}: correctness parity failed; benchmark evidence is invalid`);
+        this.code = code;
+        this.report = report;
+        this.name = 'StorageQualificationError';
+    }
+}
+export function verifyExactRecords(expected, observed) {
+    const key = (record) => `${record.identity.tenant}\0${record.identity.subsystem}\0${record.identity.path}`;
+    const expectedByKey = new Map(expected.map(record => [key(record), record]));
+    const observedByKey = new Map(observed.map(record => [key(record), record]));
+    const missing = [...expectedByKey.keys()].filter(item => !observedByKey.has(item)).sort();
+    const unexpected = [...observedByKey.keys()].filter(item => !expectedByKey.has(item)).sort();
+    const corrupt = [...expectedByKey].filter(([item, record]) => {
+        const candidate = observedByKey.get(item);
+        return candidate !== undefined && digestRecords([record]) !== digestRecords([candidate]);
+    }).map(([item]) => item).sort();
+    return { valid: missing.length === 0 && unexpected.length === 0 && corrupt.length === 0, missing, unexpected, corrupt };
+}
+export function assertCurrentStorageEvidence(report, commit) {
+    if (report.schemaVersion !== STORAGE_QUALIFICATION_REPORT || !report.verification.valid) {
+        throw new Error('storage performance claim lacks a valid qualification record');
+    }
+    if (report.scope.commit !== commit)
+        throw new Error('storage qualification record is stale for the requested commit');
+    if (report.scope.declaredRecords !== report.scope.observedRecords)
+        throw new Error('storage qualification scope is incomplete');
+}
+function mutationFor(record, idempotencyKey) {
+    return { operation: record.tombstone ? 'delete' : 'upsert', record, idempotencyKey };
+}
+function distribute(records, workers) {
+    if (!Number.isInteger(workers) || workers < 1 || workers > 32)
+        throw new Error('writers must be an integer from 1 through 32');
+    const buckets = Array.from({ length: workers }, () => []);
+    records.forEach((record, index) => buckets[index % workers].push(record));
+    return buckets;
+}
+function percentiles(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const at = (percentile) => sorted[Math.min(Math.ceil(percentile * sorted.length) - 1, sorted.length - 1)] ?? 0;
+    return { p50: at(0.5), p95: at(0.95), p99: at(0.99) };
+}
+function isRetryable(error) {
+    return typeof error === 'object' && error !== null && 'retryable' in error && error.retryable === true;
+}
+function bounded(value, fallback, min, max, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < min || resolved > max)
+        throw new Error(`${label} must be an integer from ${min} through ${max}`);
+    return resolved;
+}
+//# sourceMappingURL=qualification.js.map

package/dist/src/update/notifier.mjs

@@ -41,6 +41,7 @@ const CACHE_FILE = path.join(CACHE_DIR, 'update-notifier.json');
  * `lastCheckAt` timestamp in the cache file.
  */
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 
 /**
  * Hard timeout for the npm registry HTTPS request. Keeps the spawned
@@ -51,8 +52,8 @@ const NETWORK_TIMEOUT_MS = 10_000;
 /**
  * Read an env var and return true iff it's set to a truthy value.
  */
-function envFlag(name) {
-  const v = process.env[name];
+function envFlag(name, env = process.env) {
+  const v = env[name];
   if (!v) return false;
   return v !== '0' && v.toLowerCase() !== 'false';
 }
@@ -60,17 +61,21 @@ function envFlag(name) {
 /**
  * True iff update checking is currently disabled by env / CI conventions.
  */
-function isDisabled() {
-  if (envFlag('NO_UPDATE_NOTIFIER')) return true;
-  if (envFlag('AIWG_NO_UPDATE_CHECK')) return true;
-  if (envFlag('CI')) return true;
-  if (envFlag('GITHUB_ACTIONS')) return true;
-  if (envFlag('GITLAB_CI')) return true;
+export function notificationDisabled(env = process.env, isTTY = process.stdout.isTTY) {
+  if (envFlag('NO_UPDATE_NOTIFIER', env)) return true;
+  if (envFlag('AIWG_NO_UPDATE_CHECK', env)) return true;
+  if (envFlag('CI', env)) return true;
+  if (envFlag('GITHUB_ACTIONS', env)) return true;
+  if (envFlag('GITLAB_CI', env)) return true;
   // Non-interactive terminals shouldn't get a notice they can't act on.
-  if (!process.stdout.isTTY) return true;
+  if (!isTTY) return true;
   return false;
 }
 
+function isDisabled() {
+  return notificationDisabled();
+}
+
 /**
  * Read the update-notifier cache. Returns null if absent or malformed.
  */
@@ -168,6 +173,35 @@ export function cacheMatchesPackage(cache, packageRoot) {
   return !!(currentVersion && cache?.current === currentVersion);
 }
 
+export function formatUpdateNotice(current, latest) {
+  return (
+    `aiwg: update available ${current} → ${latest}\n` +
+    'Update: aiwg update\n' +
+    'Then rerun your command.\n'
+  );
+}
+
+export function noticeIsRateLimited(cache, intervalMs, now = Date.now()) {
+  if (!cache?.lastNotifiedAt) return false;
+  const age = now - new Date(cache.lastNotifiedAt).getTime();
+  return Number.isFinite(age) && age >= 0 && age < intervalMs;
+}
+
+/** Resolve the package that the canonical installation record says is active. */
+export function resolveActivePackageRoot(launcherPackageRoot) {
+  try {
+    const installation = loadInstallationIdentity({
+      actualRoot: launcherPackageRoot,
+      createIfMissing: false,
+    });
+    return installation?.root ?? launcherPackageRoot;
+  } catch {
+    // A broken installation identity is diagnosed by the installation
+    // preflight. The best-effort notifier must never mask that recovery path.
+    return launcherPackageRoot;
+  }
+}
+
 /**
  * Run the actual update check and write the cache file. Invoked by the
  * spawned background child via `node src/update/notifier.mjs --check`.
@@ -192,7 +226,12 @@ async function runCheck(packageRoot) {
  */
 export function scheduleBackgroundCheck(packageRoot) {
   if (isDisabled()) return;
-  const installation = loadInstallationIdentity({ actualRoot: packageRoot, createIfMissing: false });
+  let installation;
+  try {
+    installation = loadInstallationIdentity({ actualRoot: packageRoot, createIfMissing: false });
+  } catch {
+    return;
+  }
   if (installation?.checkOnStartup === false) return;
 
   const cache = readCache();
@@ -228,14 +267,20 @@ export function scheduleBackgroundCheck(packageRoot) {
  */
 export function maybePrintNotice(packageRoot) {
   if (isDisabled()) return;
-  const installation = loadInstallationIdentity({ actualRoot: packageRoot, createIfMissing: false });
+  let installation;
+  try {
+    installation = loadInstallationIdentity({ actualRoot: packageRoot, createIfMissing: false });
+  } catch {
+    return;
+  }
   if (installation?.checkOnStartup === false) return;
   const cache = readCache();
   if (!cacheMatchesPackage(cache, packageRoot)) return;
   if (!cache?.hasUpdate || !cache.current || !cache.latest) return;
-  // One-line, non-intrusive. Users who want to update run `aiwg update`.
-  const msg = `aiwg: update available ${cache.current} → ${cache.latest} (run: aiwg update)`;
-  process.stderr.write(`\n${msg}\n`);
+  const noticeInterval = installation?.updateCheckInterval ?? NOTICE_INTERVAL_MS;
+  if (noticeIsRateLimited(cache, noticeInterval)) return;
+  process.stderr.write(formatUpdateNotice(cache.current, cache.latest));
+  writeCache({ ...cache, lastNotifiedAt: new Date().toISOString() });
 }
 
 // ── Child-process entry ────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.25",
+  "version": "2026.8.26",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",