fullstackgtm 0.23.1 → 0.24.0

package/docs/api.md

@@ -59,8 +59,10 @@ release.
 
 Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
 `apply`, `suggest`, `call` (`parse` / `score` / `link` / `plan`), `resolve`,
+`bulk-update`, `dedupe`, `reassign`, `fix`,
 `market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
-`axes` / `report` / `refresh`), `rules`, `profiles`, `doctor`.
+`axes` / `overlay` / `scale` / `report` / `refresh`),
+`enrich` (`append` / `refresh` / `ingest` / `status`), `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
 (`--fail-on`, `--fail-on-new-findings`). `--json` everywhere; JSON output shapes are stable.
 
@@ -80,19 +82,59 @@ deliverable in markdown or self-contained HTML: severity counts, prose summary,
 per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
 `auditReportToHtml` expose the same rendering programmatically.
 
+## Governed write verbs
+
+Plan builders behind `bulk-update`, `dedupe`, and `reassign` — every one
+emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
+
+- `buildBulkUpdatePlan(snapshot, options: BulkUpdateOptions)` with
+  `parseWhere` (filter expressions: `=`, `!=`, `~`, `!~`, `:empty`,
+  `:notempty`, `|` any-of, relational pseudo-fields) and
+  `isFilterableField`. Filters are re-verified per record at apply time;
+  `from:<sourceField>` values derive per record from the snapshot.
+- `buildDedupePlan(snapshot, options: DedupeOptions)` with `dedupeKey` —
+  duplicate groups by normalized identity key, one `merge_records` per group,
+  deterministic survivor selection (`richest` / `oldest`).
+- `buildReassignPlans(snapshot, options: ReassignOptions)` — one plan per
+  `ReassignObjectType`, account-lifted scoping, stage exclusions.
+
+`fix` is CLI-only composition of existing surfaces (audit → suggest →
+approve → apply for one rule).
+
+## Enrich
+
+Governed third-party enrichment (spec-first; `enrich.config.json` validated
+by `parseEnrichConfig` / `loadEnrichConfig`, types `EnrichConfig`,
+`EnrichFieldConfig`, `EnrichSourceConfig`): `buildEnrichPlan` matches staged
+or pulled source records to CRM records (`matchSourceRecord` — ordered keys,
+`MatchOutcome` of matched / unmatched / ambiguous) and emits fill-blanks-only
+operations. `createFileEnrichRunStore` / `EnrichRunStore` is the profile-scoped
+append-only run store (resume cursor, per-record/per-field `enrichedAt`
+stamps read by `latestStamps` / `selectStaleWork`). `parseCsv` is the
+dependency-free CSV intake; the Apollo client (`createApolloClient`,
+`pullApolloRecords`, 429-aware with `Retry-After`) is the first `api`-kind
+source.
+
 ## Market map
 
-Newer surface (0.16–0.18); shapes are settling toward the 1.0 contract. A live
+Newer surface (0.16–0.23); shapes are settling toward the 1.0 contract. A live
 model of the competitive category: claim taxonomy + vendor registry as a
 reviewable `market.config.json` (`MarketConfig`, `MarketClaim`, `MarketVendor`,
-`MarketAxis`), content-addressed page captures (`captureMarket`,
-`loadCaptureTexts`), append-only observations (`ObservationSet`,
-`MarketObservation`, `ObservationStore` / `createFileObservationStore` —
-profile-scoped under `<home>/market/<category>`), and deterministic
-derivations: `computeFrontStates` / `diffFrontStates` (front rule v1),
-`assessAxes` / `pcaTop2` / `axisPosition` (axis discovery), and
+`MarketAxis` — axes require `negativePole`/`positivePole` labels), content-addressed
+page captures (`captureMarket`, `loadCaptureTexts`), append-only observations
+(`ObservationSet`, `MarketObservation`, `ObservationStore` /
+`createFileObservationStore` — profile-scoped under `<home>/market/<category>`),
+and deterministic derivations: `computeFrontStates` / `diffFrontStates`
+(front rule v1), `assessAxes` / `pcaTop2` / `axisPosition` (axis discovery),
+`computeDirectives` / `computeOverlayStats` / `directivesToPlan`
+(`market overlay` — observations × CRM snapshot × call corpus →
+OCCUPY/PROMOTE/URGENT/RETREAT `MarketDirective`s, convertible to an
+approval-gated plan of `create_task` operations), `computeScaleIndex` /
+`scaleReportToText` (`market scale` — citable `ScaleSignal`s → within-set,
+ACV-band-stratified revenue estimates with disclosed uncertainty), and
 `marketMapToMarkdown` / `marketMapToHtml` (the field report; renders the
-primary strategic 2×2 when `axes` / `primaryAxes` are configured).
+primary strategic 2×2 when `axes` / `primaryAxes` are configured, bubbles
+area-proportional to estimated revenue share when scale signals exist).
 
 Intensity readings are proposals: `classifyMarket` (LLM, bring-your-own-key,
 provenance-marked) or `buildWorksheet` + `market observe` (agent/human). Every

package/llms.txt

@@ -44,9 +44,34 @@ elsewhere). Failed captures read UNOBSERVABLE, never ABSENT. `fronts --diff`
 = deterministic front states + drift between runs; `axes` = PCA axis
 discovery + orthogonality screen; `report` = self-contained HTML field
 report; `refresh` = capture → classify → drift → report in one command.
+`overlay --snapshot <crm.json> [--calls <files>]` joins observations to YOUR
+CRM/calls (deterministic mention matching, no LLM) and emits OCCUPY/PROMOTE/
+URGENT/RETREAT directives — each needs ≥1 observation + ≥1 CRM stat with
+sample size; below thresholds = no directive; `--save` = approval-gated
+create_task ops. `scale` = citable scaleSignals (sourceUrl + verbatim quote
+each) → revenue-space estimates calibrated within-set by acvBand, disclosed
+uncertainty; report bubbles ∝ estimated share only when signals exist.
 Storage is profile-scoped under `<home>/market/<category>`. MCP:
 `fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
 
+## Key invariants (governed write verbs)
+
+`bulk-update <object> --where … (--set|--archive|--create-task)` filters the
+snapshot into a dry-run plan; the FULL filter is re-verified per record at
+apply time (plus mid-apply rechecks); equality filters double as
+preconditions, `--require`/`--guard` add explicit ones, `--max-operations`
+caps blast radius. `--set f=from:<source>` derives per-record values (empty
+source = skip + count, never guess). `--archive` refuses records sharing an
+identity key — merge with `dedupe` instead. `dedupe <object> --key
+<domain|email|name>` = one merge_records op per duplicate group,
+deterministic survivor (`--keep richest|oldest`); merges are irreversible and
+stay low-confidence-capped at approval. `reassign --from <owner> --to
+<owner>` = ownership handoff plans per object type; `--except-deal-stage`
+also excludes records whose account has an open deal in that stage. `fix
+--rule <id>` = audit one rule → suggest → approve at the confidence bar →
+apply only with `--yes`. All four produce plans; none writes outside
+approve → apply.
+
 ## Key invariants (enrich)
 
 `fullstackgtm enrich` is governed enrichment: `append` pulls (Apollo, BYO key
@@ -62,6 +87,25 @@ CAS). Conflict policy MVP is `never`; `system-only`/`always` are phase 2 and
 refused explicitly. Run store (checkpoint + staleness ledger + `status`) is
 profile-scoped under `<home>/enrich/runs`. No cron — scheduling is horizontal.
 
+## Key invariants (schedule)
+
+`fullstackgtm schedule` is the horizontal scheduler — no feature namespace
+owns cron logic. `add "<command>" --cron "<expr>"` validates the command
+against the read/plan-side allowlist (audit, snapshot, enrich append|refresh,
+market capture|refresh, suggest, report, doctor) and the 5-field cron
+expression, but touches no crontab; `install` materializes enabled entries
+into a sentinel-delimited managed block (`# >>> fullstackgtm <profile> >>>`)
+replaced wholesale on re-install, lines outside it untouched; `uninstall`
+removes only the block. Scheduling never auto-approves: `apply` is
+schedulable ONLY as `apply --plan-id <id>` and every firing re-checks the
+plan is approved — unapproved plans record a `plan_not_approved` no-op run,
+no flag relaxes this. `schedule run <id>` is the single provider entry point
+(in-process dispatch, never shell); run records (exit code, output tail,
+artifacts: plan ids / enrich run labels, trigger cron|manual) land under
+`<home>/schedule/runs/<id>/`. `status` shows next firing and surfaces missed
+firings (visibility only — local cron has no catch-up). Providers beyond
+`local` are not yet implemented (future: codegen scaffolds, same contract).
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",

package/src/cli.ts

@@ -101,6 +101,22 @@ import {
   pullApolloRecords,
   type ApolloPullKey,
 } from "./enrichApollo.ts";
+import {
+  computeMissedFirings,
+  createFileScheduleRunStore,
+  createFileScheduleStore,
+  nextCronFiring,
+  parseCron,
+  renderManagedBlock,
+  replaceManagedBlock,
+  scheduleId,
+  systemCrontabIo,
+  tokenizeCommand,
+  validateSchedulableArgv,
+  type ScheduleEntry,
+  type ScheduleRunRecord,
+  type ScheduleRunTrigger,
+} from "./schedule.ts";
 import { resolveRecord, type ResolveCandidate } from "./resolve.ts";
 import { buildBulkUpdatePlan } from "./bulkUpdate.ts";
 import { buildDedupePlan, type DedupeOptions } from "./dedupe.ts";
@@ -216,6 +232,16 @@ Usage:
                                                value) → with --yes, apply through the provider and print a
                                                stage-by-stage summary. Without --yes it stops after
                                                approval and prints the apply command.
+  fullstackgtm schedule add "<command>" --cron "<expr>" [--label <name>] [--provider local]
+  fullstackgtm schedule list | remove <id> | enable <id> | disable <id> | run <id>
+  fullstackgtm schedule install | uninstall [--provider local]
+  fullstackgtm schedule status [<id>] [--runs <n>]
+                                               declare a cadence for any read/plan-side command (audit,
+                                               snapshot, enrich append|refresh, market capture|refresh,
+                                               suggest, report, doctor); install materializes enabled
+                                               entries into a sentinel-delimited managed crontab block.
+                                               Scheduling never auto-approves: apply is schedulable only
+                                               as apply --plan-id <id>, re-checked approved at run time.
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -1731,6 +1757,421 @@ async function enrichStatus(store: EnrichRunStore, rest: string[], configFile: s
   }
 }
 
+/**
+ * The schedule layer: declarative cadences for read/plan-side commands,
+ * materialized through a provider (MVP: the user crontab), with an
+ * append-only run history. The governance invariant — scheduling never
+ * auto-approves — is enforced at `add` time and re-checked at `run` time.
+ * Spec: docs/schedule.md (monorepo).
+ */
+async function scheduleCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+
+  // Catch --help BEFORE any store read, credential access, or crontab
+  // round-trip (the enrich/market early-catch pattern — `schedule install
+  // --help` must never touch the crontab).
+  if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
+    console.log(`Usage:
+schedule add "<fullstackgtm command>" --cron "<expr>" [--label <name>] [--provider local]
+schedule list [--json]
+schedule remove <id>
+schedule enable <id> | disable <id>
+schedule run <id>                     execute now; the single entry point every provider's timer calls
+schedule install [--provider local]   render enabled entries into the managed crontab block
+schedule uninstall [--provider local] remove the managed block (nothing else)
+schedule status [<id>] [--runs <n>] [--json]
+
+add validates the command against the schedulable allowlist — read/plan-side
+only: audit, snapshot, enrich append|refresh, market capture|refresh,
+suggest, report, doctor — and parses the 5-field cron expression (*, lists,
+ranges, steps), but touches NO crontab: entries are declarative until install
+materializes them (the plan/apply split — declare, then deliberately
+activate).
+
+Scheduling never auto-approves. apply is schedulable ONLY as
+\`apply --plan-id <id>\`, and every firing re-checks the plan's status is
+approved — an unapproved plan records a plan_not_approved no-op run instead
+of executing. There is no flag that relaxes this. Unattended runs accumulate
+proposals (plans, run records, reports), never surprise CRM writes.
+
+install renders all enabled entries into a sentinel-delimited block
+(# >>> fullstackgtm <profile> >>> ... # <<< fullstackgtm <profile> <<<) in
+the user crontab; each line invokes \`schedule run <id> --profile <profile>\`
+and nothing else. Re-install replaces the block wholesale and never touches
+lines outside the sentinels. Providers other than local (modal, aws) are not
+yet implemented — they will be scaffold generators calling the same
+\`schedule run\` contract.
+
+run executes the command in-process and records the outcome (exit code,
+output tail, artifacts: plan ids / enrich run labels) under the profile's
+schedule/runs/<id>/; the exit code propagates. Manual runs record
+trigger: manual. status shows next firing and surfaces missed firings
+(laptop asleep = cron skips silently; visibility only, no catch-up).`);
+    return;
+  }
+
+  const store = createFileScheduleStore();
+  const runStore = createFileScheduleRunStore();
+
+  if (subcommand === "add") {
+    const commandText = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+    if (!commandText) {
+      throw new Error('Usage: fullstackgtm schedule add "<fullstackgtm command>" --cron "<expr>" [--label <name>] [--provider local]');
+    }
+    const cronText = option(rest, "--cron");
+    if (!cronText) throw new Error('schedule add requires --cron "<minute hour day-of-month month day-of-week>"');
+    requireLocalScheduleProvider(option(rest, "--provider") ?? "local");
+
+    let argv = tokenizeCommand(commandText);
+    if (argv[0] === "fullstackgtm") argv = argv.slice(1);
+    validateSchedulableArgv(argv);
+    const cron = parseCron(cronText);
+    const next = nextCronFiring(cron, new Date()); // also rejects never-firing expressions
+    const createdAt = new Date().toISOString();
+    const label =
+      option(rest, "--label") ??
+      argv.filter((arg) => !arg.startsWith("--")).slice(0, 2).join("-").replace(/[^\w.-]+/g, "-");
+    const entry: ScheduleEntry = {
+      id: scheduleId(label, cron.source, argv, createdAt),
+      label,
+      argv,
+      cron: cron.source,
+      provider: "local",
+      enabled: true,
+      createdAt,
+    };
+    await store.add(entry);
+    console.log(`Added ${entry.id} "${label}": \`${argv.join(" ")}\` at \`${cron.source}\` (next firing: ${next.toISOString()}).`);
+    console.log("Declarative until materialized — activate with `fullstackgtm schedule install`.");
+    return;
+  }
+
+  if (subcommand === "list") {
+    const entries = await store.list();
+    const now = new Date();
+    const withNext = entries.map((entry) => ({
+      ...entry,
+      nextFiring: entry.enabled ? safeNextFiring(entry.cron, now) : null,
+    }));
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(withNext, null, 2));
+      return;
+    }
+    if (entries.length === 0) {
+      console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
+      return;
+    }
+    for (const entry of withNext) {
+      console.log(
+        `${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron.padEnd(14)} next ${entry.nextFiring ?? "—"}  ${entry.label}: ${entry.argv.join(" ")}`,
+      );
+    }
+    console.log("\nEntries are declarative — `schedule install` materializes enabled ones into the crontab.");
+    return;
+  }
+
+  if (subcommand === "remove") {
+    const id = positionalArg(rest, "Usage: fullstackgtm schedule remove <id>");
+    if (!(await store.remove(id))) throw new Error(`No schedule with id ${id}.`);
+    console.log(`Removed ${id}. Run \`fullstackgtm schedule install\` to update the crontab block.`);
+    return;
+  }
+
+  if (subcommand === "enable" || subcommand === "disable") {
+    const id = positionalArg(rest, `Usage: fullstackgtm schedule ${subcommand} <id>`);
+    const entry = await store.setEnabled(id, subcommand === "enable");
+    console.log(
+      `${subcommand === "enable" ? "Enabled" : "Disabled"} ${entry.id} "${entry.label}". ` +
+        "Run `fullstackgtm schedule install` to update the crontab block.",
+    );
+    return;
+  }
+
+  if (subcommand === "run") {
+    const id = positionalArg(rest, "Usage: fullstackgtm schedule run <id>");
+    const entry = await store.get(id);
+    if (!entry) throw new Error(`No schedule with id ${id} in profile "${activeProfile()}".`);
+    if (!entry.enabled) {
+      throw new Error(`Schedule ${id} is disabled — enable it with \`fullstackgtm schedule enable ${id}\`.`);
+    }
+    const trigger = (option(rest, "--trigger") ?? "manual") as ScheduleRunTrigger;
+    if (trigger !== "cron" && trigger !== "manual") {
+      throw new Error("--trigger must be cron or manual");
+    }
+    const run = await executeScheduledRun(entry, trigger);
+    if (run.exitCode !== 0) process.exitCode = run.exitCode;
+    return;
+  }
+
+  if (subcommand === "install" || subcommand === "uninstall") {
+    requireLocalScheduleProvider(option(rest, "--provider") ?? "local");
+    const profile = activeProfile();
+    const io = systemCrontabIo();
+    const existing = io.read();
+    if (subcommand === "uninstall") {
+      io.write(replaceManagedBlock(existing, profile, null));
+      console.log(`Removed the fullstackgtm managed crontab block for profile "${profile}" (lines outside the sentinels untouched).`);
+      return;
+    }
+    const enabled = (await store.list()).filter((entry) => entry.enabled && entry.provider === "local");
+    if (enabled.length === 0) {
+      io.write(replaceManagedBlock(existing, profile, null));
+      console.log(`No enabled schedules for profile "${profile}" — removed the managed block.`);
+      return;
+    }
+    const block = renderManagedBlock(profile, enabled, scheduleCliInvocation());
+    io.write(replaceManagedBlock(existing, profile, block));
+    console.log(
+      `Installed ${enabled.length} schedule(s) into the managed crontab block for profile "${profile}". ` +
+        "Re-running install replaces the block wholesale; `schedule uninstall` removes it.",
+    );
+    return;
+  }
+
+  if (subcommand === "status") {
+    const id = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+    const entries = await store.list();
+    const selected = id ? entries.filter((entry) => entry.id === id) : entries;
+    if (id && selected.length === 0) throw new Error(`No schedule with id ${id}.`);
+    if (selected.length === 0) {
+      console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
+      return;
+    }
+    const showRuns = numericOption(rest, "--runs");
+    const now = new Date();
+    const report = [] as Array<Record<string, unknown>>;
+    for (const entry of selected) {
+      const runs = await runStore.list(entry.id);
+      const last = runs.length > 0 ? runs[runs.length - 1] : null;
+      let streak = 0;
+      for (let index = runs.length - 1; index >= 0; index -= 1) {
+        if ((runs[index].exitCode === 0) !== (last!.exitCode === 0)) break;
+        streak += 1;
+      }
+      const missed = computeMissedFirings(entry, runs, now);
+      report.push({
+        id: entry.id,
+        label: entry.label,
+        argv: entry.argv,
+        cron: entry.cron,
+        enabled: entry.enabled,
+        nextFiring: entry.enabled ? safeNextFiring(entry.cron, now) : null,
+        lastRun: last
+          ? {
+              firedAt: last.firedAt,
+              trigger: last.trigger,
+              exitCode: last.exitCode,
+              noopReason: last.noopReason,
+              artifacts: last.artifacts,
+            }
+          : null,
+        streak: last ? { outcome: last.exitCode === 0 ? "success" : "failure", length: streak } : null,
+        missedFirings: missed.missed.map((firing) => firing.toISOString()),
+        missedFiringsCapped: missed.capped,
+        runs: showRuns !== undefined ? runs.slice(-showRuns) : undefined,
+      });
+    }
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    for (const entry of report) {
+      const last = entry.lastRun as { firedAt: string; trigger: string; exitCode: number; noopReason?: string; artifacts: { planIds: string[]; runLabels: string[] } } | null;
+      const streak = entry.streak as { outcome: string; length: number } | null;
+      const missed = entry.missedFirings as string[];
+      console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron}  ${entry.label}: ${(entry.argv as string[]).join(" ")}`);
+      console.log(`  next: ${entry.nextFiring ?? "— (disabled)"}`);
+      if (last) {
+        const artifacts = [
+          ...last.artifacts.planIds.map((planId) => `plan ${planId}`),
+          ...last.artifacts.runLabels.map((runLabel) => `run ${runLabel}`),
+        ];
+        console.log(
+          `  last: ${last.firedAt} (${last.trigger}) exit ${last.exitCode}` +
+            (last.noopReason ? ` — no-op: ${last.noopReason}` : "") +
+            (artifacts.length ? ` — ${artifacts.join(", ")}` : ""),
+        );
+        console.log(`  streak: ${streak!.length} ${streak!.outcome}(s)`);
+      } else {
+        console.log("  last: never fired");
+      }
+      if (missed.length > 0) {
+        console.log(
+          `  missed: ${missed.length}${entry.missedFiringsCapped ? "+" : ""} expected firing(s) with no run record ` +
+            `(latest: ${missed[missed.length - 1]}) — local cron has no catch-up; this is visibility only`,
+        );
+      }
+      const runs = entry.runs as ScheduleRunRecord[] | undefined;
+      if (runs) {
+        for (const run of runs) {
+          console.log(`    ${run.firedAt}  ${run.trigger.padEnd(6)} exit ${run.exitCode}${run.noopReason ? `  no-op: ${run.noopReason}` : ""}`);
+        }
+      }
+    }
+    return;
+  }
+
+  throw new Error(
+    `Unknown schedule subcommand: ${subcommand} (try: add, list, remove, enable, disable, run, install, uninstall, status)`,
+  );
+}
+
+function positionalArg(rest: string[], usage: string): string {
+  const value = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+  if (!value) throw new Error(usage);
+  return value;
+}
+
+function safeNextFiring(cron: string, now: Date): string | null {
+  try {
+    return nextCronFiring(parseCron(cron), now).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+/** The provider seam: local ships now; modal/aws arrive as scaffold generators. */
+function requireLocalScheduleProvider(provider: string) {
+  if (provider === "local") return;
+  if (provider === "modal" || provider === "aws") {
+    throw new Error(
+      `Provider "${provider}" is not yet implemented — it will be a scaffold generator that emits a ` +
+        "deploy-ready artifact whose runner calls the same `schedule run <id>` contract. MVP provider: local.",
+    );
+  }
+  throw new Error(`Unknown provider "${provider}" — not yet implemented. MVP provider: local.`);
+}
+
+/**
+ * Resolve how cron should invoke this CLI: the current node binary plus the
+ * entry script (source checkouts need --experimental-strip-types), with
+ * FSGTM_HOME pinned when set so the cron environment sees the same store.
+ */
+function scheduleCliInvocation(): string {
+  const script = process.argv[1] ? resolve(process.argv[1]) : null;
+  if (!script || !existsSync(script)) {
+    throw new Error("Cannot resolve the fullstackgtm entry point for crontab lines (process.argv[1] is missing).");
+  }
+  const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+  const parts = [quote(process.execPath)];
+  if (script.endsWith(".ts")) parts.push("--experimental-strip-types");
+  parts.push(quote(script));
+  const home = process.env.FSGTM_HOME ? `FSGTM_HOME=${quote(process.env.FSGTM_HOME)} ` : "";
+  return home + parts.join(" ");
+}
+
+/**
+ * The single provider entry point: execute the scheduled command in-process
+ * (dispatch into the CLI router — never a shell), capture the output tail and
+ * exit code as a run record, and hand the exit code back to the caller. Cron
+ * calls it, cloud providers will call it, and a human running it manually
+ * produces the same record (trigger: manual).
+ *
+ * Governance re-checks happen here, not just at `add` time: the allowlist is
+ * re-validated (schedules.json is user-editable), and a scheduled apply
+ * hard-checks the plan is approved — an unapproved plan records a
+ * plan_not_approved no-op run and does NOT execute. Scheduling never
+ * auto-approves.
+ */
+async function executeScheduledRun(
+  entry: ScheduleEntry,
+  trigger: ScheduleRunTrigger,
+): Promise<ScheduleRunRecord> {
+  const runStore = createFileScheduleRunStore();
+  const firedAt = new Date().toISOString();
+  const noop = async (
+    reason: NonNullable<ScheduleRunRecord["noopReason"]>,
+    exitCode: number,
+    message: string,
+  ): Promise<ScheduleRunRecord> => {
+    const run: ScheduleRunRecord = {
+      scheduleId: entry.id,
+      firedAt,
+      completedAt: new Date().toISOString(),
+      trigger,
+      exitCode,
+      outputTail: message,
+      artifacts: { planIds: [], runLabels: [] },
+      noopReason: reason,
+    };
+    await runStore.record(run);
+    console.error(message);
+    return run;
+  };
+
+  try {
+    validateSchedulableArgv(entry.argv);
+  } catch (error) {
+    return noop("not_schedulable", 1, error instanceof Error ? error.message : String(error));
+  }
+  if (entry.argv[0] === "apply") {
+    const planId = option(entry.argv.slice(1), "--plan-id")!;
+    const stored = await createFilePlanStore().get(planId);
+    const status = stored ? stored.status : "missing";
+    if (status !== "approved") {
+      // The governance gate holding is not a machinery failure: exit 0, with
+      // the refusal recorded on the run for `schedule status` to surface.
+      return noop(
+        "plan_not_approved",
+        0,
+        `Plan ${planId} is ${status}, not approved — scheduled apply refuses to execute. ` +
+          `Scheduling never auto-approves; review and approve with \`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`,
+      );
+    }
+  }
+
+  // Artifact attribution by store diff: anything new in the plan store or the
+  // enrich run store after the command ran was produced by this firing.
+  const planStore = createFilePlanStore();
+  const plansBefore = new Set((await planStore.list()).map((stored) => stored.plan.id));
+  const enrichStore = createFileEnrichRunStore();
+  const enrichBefore = new Set((await enrichStore.list()).map((run) => run.runLabel));
+
+  const lines: string[] = [];
+  const originalLog = console.log;
+  const originalError = console.error;
+  const tee =
+    (original: (...args: unknown[]) => void) =>
+    (...args: unknown[]) => {
+      for (const line of args.map(String).join(" ").split("\n")) lines.push(line);
+      original(...args);
+    };
+  console.log = tee(originalLog);
+  console.error = tee(originalError);
+  const priorExitCode = process.exitCode;
+  process.exitCode = undefined;
+  let exitCode = 0;
+  try {
+    await runCli([...entry.argv]);
+    exitCode = typeof process.exitCode === "number" ? process.exitCode : 0;
+  } catch (error) {
+    exitCode = 1;
+    lines.push(error instanceof Error ? error.message : String(error));
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
+    process.exitCode = priorExitCode;
+  }
+
+  const planIds = (await planStore.list())
+    .map((stored) => stored.plan.id)
+    .filter((planId) => !plansBefore.has(planId));
+  const runLabels = (await enrichStore.list())
+    .map((run) => run.runLabel)
+    .filter((runLabel) => !enrichBefore.has(runLabel));
+  const run: ScheduleRunRecord = {
+    scheduleId: entry.id,
+    firedAt,
+    completedAt: new Date().toISOString(),
+    trigger,
+    exitCode,
+    outputTail: lines.slice(-50).join("\n"),
+    artifacts: { planIds, runLabels },
+  };
+  await runStore.record(run);
+  return run;
+}
+
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
  * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
@@ -2806,8 +3247,8 @@ export async function runCli(argv: string[]) {
   }
   // Commands without bespoke help fall back to the top-level usage on --help
   // instead of executing (audit used to silently run the sample audit).
-  // call/market/enrich/bulk-update print their own richer help.
-  if (!["call", "market", "enrich", "bulk-update"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
+  // call/market/enrich/bulk-update/schedule print their own richer help.
+  if (!["call", "market", "enrich", "bulk-update", "schedule"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
     console.log(usage());
     return;
   }
@@ -2876,6 +3317,10 @@ export async function runCli(argv: string[]) {
     await enrichCommand(args);
     return;
   }
+  if (command === "schedule") {
+    await scheduleCommand(args);
+    return;
+  }
   if (command === "profiles") {
     profilesCommand(args);
     return;

package/src/index.ts

@@ -254,6 +254,32 @@ export {
   type VendorScale,
 } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
+export {
+  computeMissedFirings,
+  createFileScheduleRunStore,
+  createFileScheduleStore,
+  cronMatches,
+  crontabSentinels,
+  expectedFirings,
+  nextCronFiring,
+  parseCron,
+  renderManagedBlock,
+  replaceManagedBlock,
+  scheduleId,
+  scheduleRunsDir,
+  schedulesPath,
+  systemCrontabIo,
+  tokenizeCommand,
+  validateSchedulableArgv,
+  type CronExpression,
+  type CrontabIo,
+  type ScheduleEntry,
+  type ScheduleProvider,
+  type ScheduleRunRecord,
+  type ScheduleRunStore,
+  type ScheduleRunTrigger,
+  type ScheduleStore,
+} from "./schedule.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {
   ApprovalStatus,