@chendpoc/pi-memory 0.2.4 → 0.3.2

package/dist/redaction/patterns/llm.js

@@ -0,0 +1,144 @@
+import { distanceBetweenRanges } from "../utils.js";
+/** osv-scalibr/veles/secrets/mistralapikey — 32-char key within 200 chars of Mistral context. */
+const MISTRAL_CONTEXT_RE = /\bmistral(?:ai)?(?:[_-]?(?:api[_-]?)?key)?\b|api\.mistral\.ai/gi;
+const MISTRAL_KEY_RE = /\b([A-Za-z0-9]{32})\b/g;
+const MISTRAL_MAX_DISTANCE = 200;
+/**
+ * Mistral keys are 32-char alphanumeric with no prefix — match only when a Mistral
+ * context marker (e.g. mistral_api_key, api.mistral.ai) is within 200 chars.
+ */
+function matchMistralApiKey(text) {
+    const contexts = [];
+    MISTRAL_CONTEXT_RE.lastIndex = 0;
+    let contextMatch;
+    while ((contextMatch = MISTRAL_CONTEXT_RE.exec(text)) !== null) {
+        contexts.push({
+            start: contextMatch.index,
+            end: contextMatch.index + contextMatch[0].length,
+        });
+    }
+    if (contexts.length === 0) {
+        return [];
+    }
+    const spans = [];
+    MISTRAL_KEY_RE.lastIndex = 0;
+    let keyMatch;
+    while ((keyMatch = MISTRAL_KEY_RE.exec(text)) !== null) {
+        const captured = keyMatch[1];
+        const start = keyMatch.index;
+        const end = start + captured.length;
+        const paired = contexts.some((ctx) => distanceBetweenRanges(ctx.start, ctx.end, start, end) <= MISTRAL_MAX_DISTANCE);
+        if (paired) {
+            spans.push({ start, end });
+        }
+    }
+    return spans;
+}
+/** LLM / AI inference provider keys. */
+export const llmPatterns = [
+    // openai/openai.go
+    {
+        id: "openai-api-key",
+        source: "trufflehog/pkg/detectors/openai",
+        keywords: ["T3BlbkFJ"],
+        match: /\b(sk-(?:(?:proj|svcacct|service)-[A-Za-z0-9_-]+|[a-zA-Z0-9]+)T3BlbkFJ[A-Za-z0-9_-]+)\b/g,
+    },
+    // anthropic/anthropic.go
+    {
+        id: "anthropic-api-key",
+        source: "trufflehog/pkg/detectors/anthropic",
+        keywords: ["sk-ant-api03", "sk-ant-admin01", "sk-ant-"],
+        match: /\b(sk-ant-(?:admin01|api03)-[\w-]{93}AA)\b/g,
+    },
+    // groq/groq.go
+    {
+        id: "groq-api-key",
+        source: "trufflehog/pkg/detectors/groq",
+        keywords: ["gsk_"],
+        match: /\b(gsk_[a-zA-Z0-9]{52})\b/g,
+    },
+    // Google Gemini / Maps / GCP consumer API keys (AIzaSy…)
+    {
+        id: "google-api-key",
+        source: "pi-memory",
+        keywords: ["AIzaSy"],
+        match: /\b(AIzaSy[A-Za-z0-9\-_]{33})\b/g,
+    },
+    // openrouter/openrouter.go
+    {
+        id: "openrouter-api-key",
+        source: "trufflehog/pkg/detectors/openrouter",
+        keywords: ["sk-or-v1-"],
+        match: /\b(sk-or-v1-[0-9a-f]{64})\b/g,
+    },
+    // deepseek/deepseek.go (keyword-gated: bare sk- hex is too ambiguous)
+    {
+        id: "deepseek-api-key",
+        source: "trufflehog/pkg/detectors/deepseek",
+        keywords: ["deepseek", "DEEPSEEK"],
+        match: /\b(sk-[a-f0-9]{32})\b/g,
+    },
+    // xai/xai.go
+    {
+        id: "xai-api-key",
+        source: "trufflehog/pkg/detectors/xai",
+        keywords: ["xai-"],
+        match: /\b(xai-[0-9a-zA-Z_]{80})\b/g,
+    },
+    // huggingface/huggingface.go
+    {
+        id: "huggingface-token",
+        source: "trufflehog/pkg/detectors/huggingface",
+        keywords: ["hf_", "api_org_"],
+        match: /\b((?:hf_|api_org_)[a-zA-Z0-9]{34})\b/g,
+    },
+    // replicate/replicate.go
+    {
+        id: "replicate-token",
+        source: "trufflehog/pkg/detectors/replicate",
+        keywords: ["r8_", "replicate"],
+        match: /\b(r8_[0-9A-Za-z\-_]{37})\b/g,
+    },
+    // Perplexity (pplx-…)
+    {
+        id: "perplexity-api-key",
+        source: "pi-memory",
+        keywords: ["pplx-"],
+        match: /\b(pplx-[A-Za-z0-9_\-]{20,})\b/g,
+    },
+    // Fireworks AI (fw_…)
+    {
+        id: "fireworks-api-key",
+        source: "pi-memory",
+        keywords: ["fw_"],
+        match: /\b(fw_[A-Za-z0-9_\-]{20,})\b/g,
+    },
+    // Voyage AI embeddings (pa-…)
+    {
+        id: "voyage-api-key",
+        source: "pi-memory",
+        keywords: ["pa-"],
+        match: /\b(pa-[A-Za-z0-9_\-]{20,})\b/g,
+    },
+    // azure_openai/azure_openai.go
+    {
+        id: "azure-openai-api-key",
+        source: "trufflehog/pkg/detectors/azure_openai",
+        keywords: [".openai.azure.com"],
+        match: /(?:api[_.-]?key|openai[_.-]?key)(?:.|[\n\r]){0,40}?([a-f0-9]{32})\b/gi,
+    },
+    // gcp/gcp.go — flat service-account JSON block (provider_x509 marker)
+    {
+        id: "gcp-service-account-json",
+        source: "trufflehog/pkg/detectors/gcp",
+        keywords: ["provider_x509", "auth_provider_x509_cert_url"],
+        match: /\{[^{]+auth_provider_x509_cert_url[^}]+\}/gi,
+    },
+    // osv-scalibr/veles/secrets/mistralapikey — pairing via match()
+    {
+        id: "mistral-api-key",
+        source: "osv-scalibr/veles/secrets/mistralapikey",
+        keywords: ["mistral", "mistralai", "api.mistral.ai"],
+        match: matchMistralApiKey,
+    },
+];

package/dist/redaction/patterns/platform.d.ts

@@ -0,0 +1,3 @@
+import type { SecretPattern } from "./types.js";
+/** Dev / SaaS / cloud platform tokens (non-LLM-specific). */
+export declare const platformPatterns: readonly SecretPattern[];

package/dist/redaction/patterns/platform.js

@@ -0,0 +1,87 @@
+/** Dev / SaaS / cloud platform tokens (non-LLM-specific). */
+export const platformPatterns = [
+    // github/v2/github.go
+    {
+        id: "github-token",
+        source: "trufflehog/pkg/detectors/github/v2",
+        keywords: ["ghp_", "gho_", "ghu_", "ghs_", "ghr_", "github_pat_"],
+        match: /\b((?:ghp|gho|ghu|ghs|ghr|github_pat)_[a-zA-Z0-9_]{36,255})\b/g,
+    },
+    // pinecone/pinecone.go
+    {
+        id: "pinecone-api-key",
+        source: "trufflehog/pkg/detectors/pinecone",
+        keywords: ["pcsk_"],
+        match: /\b(pcsk_[A-Za-z0-9]{5,6}_[A-Za-z0-9]{63})\b/g,
+    },
+    // langsmith/langsmith.go
+    {
+        id: "langsmith-api-key",
+        source: "trufflehog/pkg/detectors/langsmith",
+        keywords: ["lsv2_pt_", "lsv2_sk_"],
+        match: /\b(lsv2_(?:pt|sk)_[a-f0-9]{32}_[a-f0-9]{10})\b/g,
+    },
+    // aws/access_keys/accesskey.go (access key id only; secret key needs entropy pairing)
+    {
+        id: "aws-access-key-id",
+        source: "trufflehog/pkg/detectors/aws/access_keys",
+        keywords: ["AKIA", "ABIA", "ACCA"],
+        match: /\b((?:AKIA|ABIA|ACCA)[A-Z0-9]{16})\b/g,
+    },
+    // slack/slack.go (four token types merged)
+    {
+        id: "slack-token",
+        source: "trufflehog/pkg/detectors/slack",
+        keywords: ["xoxb-", "xoxp-", "xoxa-", "xoxr-"],
+        match: /xox[bpar]-[0-9]{10,13}-[0-9]{10,13}[a-zA-Z0-9-]*/g,
+    },
+    // stripe/stripe.go (live keys only; test keys intentionally excluded)
+    {
+        id: "stripe-live-key",
+        source: "trufflehog/pkg/detectors/stripe",
+        keywords: ["k_live"],
+        match: /[rs]k_live_[a-zA-Z0-9]{20,247}/g,
+    },
+    // gitlab/v2/gitlab_v2.go
+    {
+        id: "gitlab-pat",
+        source: "trufflehog/pkg/detectors/gitlab/v2",
+        keywords: ["glpat-"],
+        match: /\b(glpat-[a-zA-Z0-9\-=_]{20,22})\b/g,
+    },
+    // npmtokenv2/npmtokenv2.go
+    {
+        id: "npm-token",
+        source: "trufflehog/pkg/detectors/npmtokenv2",
+        keywords: ["npm_"],
+        match: /(npm_[0-9a-zA-Z]{36})/g,
+    },
+    // supabasetoken/supabasetoken.go
+    {
+        id: "supabase-token",
+        source: "trufflehog/pkg/detectors/supabasetoken",
+        keywords: ["sbp_"],
+        match: /\b(sbp_[a-z0-9]{40})\b/g,
+    },
+    // linearapi/linearapi.go
+    {
+        id: "linear-api-key",
+        source: "trufflehog/pkg/detectors/linearapi",
+        keywords: ["lin_api_"],
+        match: /\b(lin_api_[0-9A-Za-z]{40})\b/g,
+    },
+    // sendgrid/sendgrid.go
+    {
+        id: "sendgrid-api-key",
+        source: "trufflehog/pkg/detectors/sendgrid",
+        keywords: ["SG."],
+        match: /\bSG\.[\w\-]{20,24}\.[\w\-]{39,50}\b/g,
+    },
+    // postman/postman.go
+    {
+        id: "postman-api-key",
+        source: "trufflehog/pkg/detectors/postman",
+        keywords: ["PMAK-"],
+        match: /\b(PMAK-[a-zA-Z0-9\-]{59})\b/g,
+    },
+];

package/dist/redaction/patterns/types.d.ts

@@ -0,0 +1,18 @@
+export type SecretMatchSpan = {
+    start: number;
+    end: number;
+};
+/**
+ * Per-rule detector: RegExp for prefix/block rules; function when proximity pairing is required.
+ * Custom matchers return spans without patternId — collectSpans adds the rule id.
+ */
+export type SecretPatternMatcher = RegExp | ((text: string) => readonly SecretMatchSpan[]);
+export type SecretPattern = {
+    /** Stable id for debug metrics (no secret material). */
+    id: string;
+    /** TruffleHog detector path, or "pi-memory" for local supplements. */
+    source: string;
+    /** Optional keyword pre-filter (mirrors TruffleHog Keywords()). */
+    keywords?: string[];
+    match: SecretPatternMatcher;
+};

package/dist/redaction/patterns/types.js

@@ -0,0 +1 @@
+export {};

package/dist/redaction/redactText.d.ts

@@ -0,0 +1,9 @@
+import type { RedactTextResult } from "./types.js";
+export type { RedactTextResult, RedactionSpan } from "./types.js";
+/** Run all secret detectors, merge overlaps, return redacted text and debug metadata. */
+export declare function redactText(text: string): RedactTextResult;
+/**
+ * True when nothing meaningful remains after redaction.
+ * MemoryStore skips the write (fail-closed) instead of persisting a lone placeholder.
+ */
+export declare function isEmptyAfterRedaction(content: string): boolean;

package/dist/redaction/redactText.js

@@ -0,0 +1,31 @@
+/**
+ * Path A redaction entry: scan text against SECRET_PATTERNS, replace hits with [REDACTED].
+ * Called from MemoryStore.prepareEntryForWrite before Ground Truth is persisted.
+ */
+import { REDACTED_PLACEHOLDER, SECRET_PATTERNS, SECRET_POLICY_VERSION, } from "./patterns/index.js";
+import { applySpans, collectSpans, mergeSpans } from "./utils.js";
+/** Run all secret detectors, merge overlaps, return redacted text and debug metadata. */
+export function redactText(text) {
+    const spans = mergeSpans(collectSpans(text, SECRET_PATTERNS));
+    const hitCount = spans.length;
+    return {
+        text: applySpans(text, spans, REDACTED_PLACEHOLDER),
+        hitCount,
+        secretHits: hitCount,
+        piiHits: 0,
+        mutated: hitCount > 0,
+        spans,
+        policyVersion: SECRET_POLICY_VERSION,
+    };
+}
+/**
+ * True when nothing meaningful remains after redaction.
+ * MemoryStore skips the write (fail-closed) instead of persisting a lone placeholder.
+ */
+export function isEmptyAfterRedaction(content) {
+    const trimmed = content.trim();
+    if (trimmed.length === 0) {
+        return true;
+    }
+    return trimmed === REDACTED_PLACEHOLDER;
+}

package/dist/redaction/types.d.ts

@@ -0,0 +1,19 @@
+/** Byte range of a secret match in the original string (before replacement). */
+export type RedactionSpan = {
+    start: number;
+    end: number;
+    /** Rule id(s) that matched; merged spans join ids with "+". */
+    patternId: string;
+};
+export type RedactTextResult = {
+    text: string;
+    /** Number of merged spans (not raw regex hit count). */
+    hitCount: number;
+    secretHits: number;
+    /** Always 0 — pi-memory Path A covers secrets only, not PII. */
+    piiHits: number;
+    mutated: boolean;
+    spans: RedactionSpan[];
+    /** SECRET_POLICY_VERSION at time of scan; for debug / policy drift audits. */
+    policyVersion: string;
+};

package/dist/redaction/types.js

@@ -0,0 +1 @@
+export {};

package/dist/redaction/utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Redaction pipeline helpers.
+ *
+ * Flow: hasKeyword (gate) → runPatternMatch (per rule) → collectSpans → mergeSpans → applySpans
+ */
+import type { SecretMatchSpan, SecretPattern, SecretPatternMatcher } from "./patterns/types.js";
+import type { RedactionSpan } from "./types.js";
+/** Gap between two ranges; 0 when overlapping or adjacent. Used by proximity matchers. */
+export declare function distanceBetweenRanges(aStart: number, aEnd: number, bStart: number, bEnd: number): number;
+/**
+ * TruffleHog-style keyword gate: skip expensive regex / pairing when no keyword appears.
+ * Empty keywords → always run (used by rules with strong standalone prefixes).
+ */
+export declare function hasKeyword(text: string, keywords: readonly string[] | undefined): boolean;
+/**
+ * Execute one rule's `match` field: either a custom fn or a global RegExp scan.
+ * Prefers capture group 1 when present so only the secret token is redacted, not surrounding syntax.
+ */
+export declare function runPatternMatch(text: string, matcher: SecretPatternMatcher): SecretMatchSpan[];
+/** Run every pattern that passes keyword gate; attach rule id to each raw span. */
+export declare function collectSpans(text: string, patterns: readonly SecretPattern[]): RedactionSpan[];
+/**
+ * Collapse overlapping / adjacent hits into one span so we emit a single [REDACTED].
+ * Example: `Bearer ghp_xxx` matched by both bearer-token and github-token → one placeholder.
+ */
+export declare function mergeSpans(spans: RedactionSpan[]): RedactionSpan[];
+/** Replace matched ranges right-to-left so earlier span indices stay valid while slicing. */
+export declare function applySpans(text: string, spans: RedactionSpan[], placeholder: string): string;

package/dist/redaction/utils.js

@@ -0,0 +1,106 @@
+/**
+ * Redaction pipeline helpers.
+ *
+ * Flow: hasKeyword (gate) → runPatternMatch (per rule) → collectSpans → mergeSpans → applySpans
+ */
+/** Gap between two ranges; 0 when overlapping or adjacent. Used by proximity matchers. */
+export function distanceBetweenRanges(aStart, aEnd, bStart, bEnd) {
+    if (aEnd < bStart) {
+        return bStart - aEnd;
+    }
+    if (bEnd < aStart) {
+        return aStart - bEnd;
+    }
+    return 0;
+}
+/**
+ * TruffleHog-style keyword gate: skip expensive regex / pairing when no keyword appears.
+ * Empty keywords → always run (used by rules with strong standalone prefixes).
+ */
+export function hasKeyword(text, keywords) {
+    if (!keywords || keywords.length === 0) {
+        return true;
+    }
+    const lower = text.toLowerCase();
+    for (const keyword of keywords) {
+        if (text.includes(keyword) || lower.includes(keyword.toLowerCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Execute one rule's `match` field: either a custom fn or a global RegExp scan.
+ * Prefers capture group 1 when present so only the secret token is redacted, not surrounding syntax.
+ */
+export function runPatternMatch(text, matcher) {
+    if (typeof matcher === "function") {
+        return [...matcher(text)];
+    }
+    const spans = [];
+    matcher.lastIndex = 0;
+    let result;
+    while ((result = matcher.exec(text)) !== null) {
+        const captured = result[1] ?? result[0];
+        const start = result[1] !== undefined ? result.index + result[0].indexOf(result[1]) : result.index;
+        const end = start + captured.length;
+        if (end > start) {
+            spans.push({ start, end });
+        }
+        // Avoid infinite loop on zero-width matches (e.g. lookahead-only patterns).
+        if (result[0].length === 0) {
+            matcher.lastIndex += 1;
+        }
+    }
+    return spans;
+}
+/** Run every pattern that passes keyword gate; attach rule id to each raw span. */
+export function collectSpans(text, patterns) {
+    const spans = [];
+    for (const pattern of patterns) {
+        if (!hasKeyword(text, pattern.keywords)) {
+            continue;
+        }
+        for (const span of runPatternMatch(text, pattern.match)) {
+            if (span.end > span.start) {
+                spans.push({ start: span.start, end: span.end, patternId: pattern.id });
+            }
+        }
+    }
+    return spans;
+}
+/**
+ * Collapse overlapping / adjacent hits into one span so we emit a single [REDACTED].
+ * Example: `Bearer ghp_xxx` matched by both bearer-token and github-token → one placeholder.
+ */
+export function mergeSpans(spans) {
+    if (spans.length === 0) {
+        return [];
+    }
+    const sorted = [...spans].sort((a, b) => a.start - b.start || a.end - b.end);
+    const merged = [sorted[0]];
+    for (let i = 1; i < sorted.length; i += 1) {
+        const current = sorted[i];
+        const last = merged[merged.length - 1];
+        if (current.start <= last.end) {
+            last.end = Math.max(last.end, current.end);
+            last.patternId = `${last.patternId}+${current.patternId}`;
+        }
+        else {
+            merged.push({ ...current });
+        }
+    }
+    return merged;
+}
+/** Replace matched ranges right-to-left so earlier span indices stay valid while slicing. */
+export function applySpans(text, spans, placeholder) {
+    if (spans.length === 0) {
+        return text;
+    }
+    let result = text;
+    for (let i = spans.length - 1; i >= 0; i -= 1) {
+        const span = spans[i];
+        result = result.slice(0, span.start) + placeholder + result.slice(span.end);
+    }
+    return result;
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export { buildLaunchdMaintenancePlist, buildLaunchdMaintenanceShellCommand, shellSingleQuote, type LaunchdMaintenancePlistInput, } from "./launchdPlist.js";
+export { launchAgentPlistPath, isLaunchAgentLoaded, syncLaunchdMaintenanceJob, type LaunchdSyncResult } from "./launchd.js";
+export { canSyncLaunchdInProcess, isSchedulerSyncDisabled, resolvePackageCliPath, syncMaintenanceScheduler, type SchedulerSyncResult, type SyncMaintenanceSchedulerOptions, } from "./sync.js";

package/dist/scheduler/index.js

@@ -0,0 +1,3 @@
+export { buildLaunchdMaintenancePlist, buildLaunchdMaintenanceShellCommand, shellSingleQuote, } from "./launchdPlist.js";
+export { launchAgentPlistPath, isLaunchAgentLoaded, syncLaunchdMaintenanceJob } from "./launchd.js";
+export { canSyncLaunchdInProcess, isSchedulerSyncDisabled, resolvePackageCliPath, syncMaintenanceScheduler, } from "./sync.js";

package/dist/scheduler/launchd.d.ts

@@ -0,0 +1,14 @@
+import { type LaunchdMaintenancePlistInput } from "./launchdPlist.js";
+export declare function launchAgentPlistPath(label?: string): string;
+/** True when the user LaunchAgent is registered in launchd (not merely when the plist file exists). */
+export declare function isLaunchAgentLoaded(label: string): Promise<boolean>;
+export type LaunchdSyncResult = {
+    label: string;
+    plistPath: string;
+    /** Plist bytes changed on disk. */
+    changed: boolean;
+    /** launchctl bootstrap ran because the job was missing (e.g. prior bootstrap failed). */
+    bootstrapped: boolean;
+    removedLegacy: string[];
+};
+export declare function syncLaunchdMaintenanceJob(input: LaunchdMaintenancePlistInput): Promise<LaunchdSyncResult>;

package/dist/scheduler/launchd.js

@@ -0,0 +1,69 @@
+import { execa } from "execa";
+import { existsSync } from "node:fs";
+import { unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { LAUNCHD_LABEL, LEGACY_LAUNCHD_LABELS } from "../constants/paths.js";
+import { buildLaunchdMaintenancePlist } from "./launchdPlist.js";
+export function launchAgentPlistPath(label = LAUNCHD_LABEL) {
+    return join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+}
+function launchctlDomain() {
+    const uid = process.getuid?.();
+    return uid === undefined ? null : `gui/${uid}`;
+}
+async function launchctlBootout(label) {
+    const domain = launchctlDomain();
+    const plistPath = launchAgentPlistPath(label);
+    if (domain) {
+        await execa("launchctl", ["bootout", `${domain}/${label}`], { reject: false });
+    }
+    if (existsSync(plistPath)) {
+        await execa("launchctl", ["unload", plistPath], { reject: false });
+    }
+}
+async function launchctlBootstrap(plistPath) {
+    const domain = launchctlDomain();
+    if (!domain) {
+        throw new Error("launchctl bootstrap requires a user id");
+    }
+    await execa("launchctl", ["bootstrap", domain, plistPath]);
+}
+/** True when the user LaunchAgent is registered in launchd (not merely when the plist file exists). */
+export async function isLaunchAgentLoaded(label) {
+    const domain = launchctlDomain();
+    if (!domain)
+        return false;
+    const result = await execa("launchctl", ["print", `${domain}/${label}`], { reject: false });
+    return result.exitCode === 0;
+}
+export async function syncLaunchdMaintenanceJob(input) {
+    const label = input.label;
+    const plistPath = launchAgentPlistPath(label);
+    const plist = buildLaunchdMaintenancePlist(input);
+    let previous = null;
+    if (existsSync(plistPath)) {
+        const { readFile } = await import("node:fs/promises");
+        previous = await readFile(plistPath, "utf8");
+    }
+    const removedLegacy = [];
+    for (const legacyLabel of LEGACY_LAUNCHD_LABELS) {
+        const legacyPath = launchAgentPlistPath(legacyLabel);
+        if (!existsSync(legacyPath))
+            continue;
+        await launchctlBootout(legacyLabel);
+        await unlink(legacyPath).catch(() => { });
+        removedLegacy.push(legacyLabel);
+    }
+    if (previous === plist) {
+        if (await isLaunchAgentLoaded(label)) {
+            return { label, plistPath, changed: false, bootstrapped: false, removedLegacy };
+        }
+        await launchctlBootstrap(plistPath);
+        return { label, plistPath, changed: false, bootstrapped: true, removedLegacy };
+    }
+    await writeFile(plistPath, plist, "utf8");
+    await launchctlBootout(label);
+    await launchctlBootstrap(plistPath);
+    return { label, plistPath, changed: true, bootstrapped: true, removedLegacy };
+}

package/dist/scheduler/launchdPlist.d.ts

@@ -0,0 +1,14 @@
+export type LaunchdMaintenancePlistInput = {
+    label: string;
+    nodePath: string;
+    cliPath: string;
+    envFile: string;
+    agentDir: string;
+    stdoutLog: string;
+    stderrLog: string;
+    logsDir: string;
+};
+/** Escape a string for safe inclusion inside single-quoted sh(1) arguments. */
+export declare function shellSingleQuote(value: string): string;
+export declare function buildLaunchdMaintenanceShellCommand(input: LaunchdMaintenancePlistInput): string;
+export declare function buildLaunchdMaintenancePlist(input: LaunchdMaintenancePlistInput): string;

package/dist/scheduler/launchdPlist.js

@@ -0,0 +1,62 @@
+import { CONSOLIDATE_CRON_HOUR, CONSOLIDATE_CRON_MINUTE } from "../constants/timing.js";
+/** Escape a string for safe inclusion inside single-quoted sh(1) arguments. */
+export function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+export function buildLaunchdMaintenanceShellCommand(input) {
+    const mkdir = `mkdir -p ${shellSingleQuote(input.logsDir)}`;
+    const exec = [
+        "exec",
+        shellSingleQuote(input.nodePath),
+        shellSingleQuote(input.cliPath),
+        "maintenance",
+        "--cron",
+        "--verbose",
+    ].join(" ");
+    const redirect = `>> ${shellSingleQuote(input.stdoutLog)} 2>> ${shellSingleQuote(input.stderrLog)}`;
+    return `${mkdir} && ${exec} ${redirect}`;
+}
+export function buildLaunchdMaintenancePlist(input) {
+    const shellCommand = buildLaunchdMaintenanceShellCommand(input);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(input.label)}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-c</string>
+    <string>${escapeXml(shellCommand)}</string>
+  </array>
+
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>${CONSOLIDATE_CRON_HOUR}</integer>
+    <key>Minute</key>
+    <integer>${CONSOLIDATE_CRON_MINUTE}</integer>
+  </dict>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PI_MEMORY_ENV_FILE</key>
+    <string>${escapeXml(input.envFile)}</string>
+    <key>PI_MEMORY_AGENT_DIR</key>
+    <string>${escapeXml(input.agentDir)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}

package/dist/scheduler/sync.d.ts

@@ -0,0 +1,36 @@
+export type SchedulerSyncResult = {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "synced";
+    platform: "launchd";
+    label: string;
+    plistPath: string;
+    changed: boolean;
+    bootstrapped: boolean;
+    removedLegacy: string[];
+} | {
+    status: "failed";
+    reason: string;
+    message: string;
+};
+export declare function isSchedulerSyncDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** Whether this process can attempt a user LaunchAgent sync (macOS + uid + home). */
+export declare function canSyncLaunchdInProcess(env?: NodeJS.ProcessEnv): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolvePackageCliPath(moduleUrl?: string): string;
+export type SyncMaintenanceSchedulerOptions = {
+    agentDir?: string;
+    cliPath?: string;
+    nodePath?: string;
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Install or refresh the OS maintenance scheduler (macOS launchd today).
+ * Never throws — automatic callers (postinstall, session_start, init) treat failures as best-effort.
+ */
+export declare function syncMaintenanceScheduler(opts?: SyncMaintenanceSchedulerOptions): Promise<SchedulerSyncResult>;