@namzu/sdk 54.0.0 → 55.1.0

package/src/manager/resident/consumption.ts

@@ -51,10 +51,18 @@ const receiptSchema = z
 			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Unpriced usage exceeds own usage.' })
 	})
 
-/** @experimental Host-authenticated cumulative root receipt. Cost covers this root only. */
+/**
+ * @experimental Host-authenticated cumulative root receipt. Cost covers this root only.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentConsumptionReceipt = z.infer<typeof receiptSchema>
 
-/** @experimental A host resolves only authoritative admitted claims and bounds each read. */
+/**
+ * @experimental A host resolves only authoritative admitted claims and bounds each read.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentConsumptionResolver {
 	/** Worst-case bytes read per resolution; reserved before calling the adapter. */
 	readonly maxReadBytes: number
@@ -64,7 +72,11 @@ export interface ResidentConsumptionResolver {
 	): Promise<ResidentConsumptionReceipt | null>
 }
 
-/** @experimental Bounds the entire inspection, not just each page. No inference or writes. */
+/**
+ * @experimental Bounds the entire inspection, not just each page. No inference or writes.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentConsumptionOptions {
 	readonly cursor?: number
 	readonly maxRevisions?: number
@@ -72,14 +84,22 @@ export interface ResidentConsumptionOptions {
 	readonly maxReceiptBytes?: number
 }
 
-/** @experimental Missing and deferred receipts never establish zero usage. */
+/**
+ * @experimental Missing and deferred receipts never establish zero usage.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentConsumptionAttempt extends ResidentAdmission {
 	readonly settlement: ResidentSettlement | null
 	readonly receipt: ResidentConsumptionReceipt | null
 	readonly receiptStatus: 'available' | 'missing' | 'invalid' | 'deferred' | 'duplicate-turn'
 }
 
-/** @experimental An evidence projection, not a bill or an enforced spending cap. */
+/**
+ * @experimental An evidence projection, not a bill or an enforced spending cap.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentConsumptionReport {
 	readonly scope: ResidentActivityScope
 	readonly fromRevision: number
@@ -110,6 +130,8 @@ export interface ResidentConsumptionReport {
  * @experimental Inspect cumulative root receipts once per admitted claim. Historical
  * archive/reconcile events never erase consumption. Tree tokens are a separate total:
  * adding them to own tokens would count the root twice. Descendant prices are unknown.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export async function inspectResidentConsumption(
 	source: ResidentActivitySource,

package/src/manager/resident/delivery-window.ts

@@ -1,6 +1,10 @@
 import type { ResidentDeliveryGate } from './outbox.js'
 
-/** @experimental A daily allowed delivery window in an explicit named time zone. */
+/**
+ * @experimental A daily allowed delivery window in an explicit named time zone.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentDeliveryWindowConfig {
 	readonly timeZone: string
 	/** Inclusive local minute of the day, from 0 through 1439. */
@@ -22,6 +26,8 @@ const searchMinutes = 72 * 60
  * is bounded to 72 hours and the Date range; no opening returns nextCheckAt:null.
  * Historic time zones with second-based offsets may defer up to one extra minute.
  * This gate does not schedule a timer, authorize a destination or send a message.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function createResidentDeliveryWindow(
 	config: ResidentDeliveryWindowConfig,

package/src/manager/resident/evidence-recall.ts

@@ -13,7 +13,11 @@ import { evidenceTokenKey } from '../../utils/evidence-tokens.js'
 import { type ResidentState, residentStateSchema } from './store.js'
 import type { ResidentToolEvidenceSource } from './tool-evidence.js'
 
-/** @experimental Automatic original-tool recall for exactly one admitted resident turn. */
+/**
+ * @experimental Automatic original-tool recall for exactly one admitted resident turn.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentEvidenceRecallOptions {
 	readonly source: ResidentToolEvidenceSource
 	/** Already admitted state; summaries supply search words, never new observations. */
@@ -74,6 +78,8 @@ function residentQueryWords(text: string): string[] {
  * Reuses the shared bounded ranking/rendering engine while retaining the
  * pursuit's settlement authority. No arbitrary Session discovery, saved fact
  * cache, inference, workspace reread or action replay is performed here.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function createResidentEvidenceRecallStep(
 	options: ResidentEvidenceRecallOptions,

package/src/manager/resident/history.ts

@@ -6,7 +6,11 @@ const SCAN_BYTES = 8 * 1024 * 1024
 const SCAN_REVISIONS = 32
 const TEXT_PAGE_CHARS = 6_000
 
-/** @experimental Host-bound historical scope; the upper revision never advances implicitly. */
+/**
+ * @experimental Host-bound historical scope; the upper revision never advances implicitly.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistoryScope {
 	readonly tenantId: string
 	readonly agentKey: string
@@ -14,13 +18,21 @@ export interface ResidentHistoryScope {
 	readonly throughRevision: number
 }
 
-/** @experimental Revision plus part identifies retained text within one pursuit. */
+/**
+ * @experimental Revision plus part identifies retained text within one pursuit.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistoryAddress {
 	readonly revision: number
 	readonly part: number
 }
 
-/** @experimental Summary or accepted wake input from a settled historical step. */
+/**
+ * @experimental Summary or accepted wake input from a settled historical step.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistoryMatch extends ResidentHistoryAddress {
 	readonly step: number
 	readonly claimId: string
@@ -30,7 +42,11 @@ export interface ResidentHistoryMatch extends ResidentHistoryAddress {
 	readonly matchingParts: readonly number[]
 }
 
-/** @experimental Empty query browses recent steps; cursor is the next inclusive revision. */
+/**
+ * @experimental Empty query browses recent steps; cursor is the next inclusive revision.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistorySearchOptions {
 	/** Optional per-call ceiling, 1 byte–8 MiB. Defaults to 8 MiB. */
 	readonly maxReadBytes?: number
@@ -39,7 +55,11 @@ export interface ResidentHistorySearchOptions {
 	readonly limit?: number
 }
 
-/** @experimental Counts describe this page, not the whole history. */
+/**
+ * @experimental Counts describe this page, not the whole history.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistorySearchResult {
 	readonly matches: readonly ResidentHistoryMatch[]
 	readonly nextCursor: number | null
@@ -49,14 +69,22 @@ export interface ResidentHistorySearchResult {
 	readonly incomplete: boolean
 }
 
-/** @experimental Use the returned nextOffset to continue exact Unicode-safe text. */
+/**
+ * @experimental Use the returned nextOffset to continue exact Unicode-safe text.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistoryReadOptions extends ResidentHistoryAddress {
 	readonly offset?: number
 	/** Optional per-call ceiling, 1 byte–8 MiB. Defaults to 8 MiB. */
 	readonly maxReadBytes?: number
 }
 
-/** @experimental A recorded claim remains historical evidence, not proof of current validity. */
+/**
+ * @experimental A recorded claim remains historical evidence, not proof of current validity.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistoryText extends ResidentHistoryAddress {
 	readonly step: number
 	readonly claimId: string
@@ -69,7 +97,11 @@ export interface ResidentHistoryText extends ResidentHistoryAddress {
 	readonly nextOffset: number | null
 }
 
-/** @experimental Null with unavailable revisions means unreadable evidence, not proven absence. */
+/**
+ * @experimental Null with unavailable revisions means unreadable evidence, not proven absence.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistoryReadResult {
 	readonly entry: ResidentHistoryText | null
 	readonly scannedRevisions: number
@@ -77,7 +109,11 @@ export interface ResidentHistoryReadResult {
 	readonly unavailableRevisions: readonly number[]
 }
 
-/** @experimental A backend must enforce its bound scope and bounded reads. */
+/**
+ * @experimental A backend must enforce its bound scope and bounded reads.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHistorySource {
 	readonly scope: ResidentHistoryScope
 	search(

package/src/manager/resident/host.ts

@@ -1,4 +1,5 @@
 import { setTimeout as sleep } from 'node:timers/promises'
+import { type LearningState, freezeLearning } from '../../learning/skill.js'
 import type { ResidentAgendaState, ResidentAgendaStore, ResidentPursuit } from './agenda.js'
 import {
 	type ResidentObservation,
@@ -6,12 +7,15 @@ import {
 	type ResidentSelector,
 	residentObservationSchema,
 } from './initiative.js'
-import { type ResidentLearningState, freezeResidentLearning } from './learning.js'
 import { type ResidentStep, stepResident } from './loop.js'
 import { type ResidentMessageInput, residentMessageInputSchema } from './outbox.js'
 import { ResidentConflictError, type ResidentDecision, residentDecisionSchema } from './store.js'
 
-/** @experimental Host result describes execution, not external-effect rollback. */
+/**
+ * @experimental Host result describes execution, not external-effect rollback.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHostResult {
 	readonly status: 'idle' | 'paused' | 'unresolved' | 'cancelled' | 'limit' | 'contended'
 	readonly stepsSettled: number
@@ -19,7 +23,11 @@ export interface ResidentHostResult {
 	readonly selection?: ResidentSelection
 }
 
-/** @experimental Explicit authorization to drive a finite number of background steps. */
+/**
+ * @experimental Explicit authorization to drive a finite number of background steps.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHostRunOptions {
 	readonly signal: AbortSignal
 	readonly maxSteps: number
@@ -29,40 +37,64 @@ export interface ResidentHostRunOptions {
 	readonly keepAlive?: boolean
 }
 
-/** @experimental Immutable context from the agenda snapshot that authorized this admission. */
+/**
+ * @experimental Immutable context from the agenda snapshot that authorized this admission.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentStepContext {
 	readonly agendaRevision: number
-	readonly learning?: ResidentLearningState
+	readonly learning?: LearningState
 }
 
-/** @experimental A developer callback may bind a different SDK turn for each pursuit. */
+/**
+ * @experimental A developer callback may bind a different SDK turn for each pursuit.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentPursuitStep = (
 	pursuit: ResidentPursuit,
 	signal: AbortSignal,
 ) => ReturnType<ResidentStep>
 
-/** @experimental Context-aware callback; existing two-argument steps remain assignable. */
+/**
+ * @experimental Context-aware callback; existing two-argument steps remain assignable.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentContextualStep = (
 	pursuit: ResidentPursuit,
 	signal: AbortSignal,
 	context: ResidentStepContext,
 ) => ReturnType<ResidentStep>
 
-/** @experimental Inspect actual outcomes and resource receipts independently of model prose. */
+/**
+ * @experimental Inspect actual outcomes and resource receipts independently of model prose.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentObserver = (
 	pursuit: ResidentPursuit,
 	decision: ResidentDecision,
 	signal: AbortSignal,
 ) => Promise<ResidentObservation>
 
-/** @experimental Host validates content and destination; null means no communication. */
+/**
+ * @experimental Host validates content and destination; null means no communication.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentMessageFactory = (
 	pursuit: ResidentPursuit,
 	decision: ResidentDecision,
 	signal: AbortSignal,
 ) => Promise<ResidentMessageInput | null>
 
-/** @experimental Opt-in local selection, observed settlement and atomic outbound intent. */
+/**
+ * @experimental Opt-in local selection, observed settlement and atomic outbound intent.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentHostOptions {
 	readonly select?: ResidentSelector
 	readonly observe?: ResidentObserver
@@ -75,6 +107,8 @@ export interface ResidentHostOptions {
  * @experimental Local driver for one durable agenda. Shared agenda admission
  * prevents overlapping pursuits across processes. Notifications are local;
  * opt-in keepAlive also rereads durable state on bounded idle timers.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export class ResidentHost {
 	private controller: AbortController | undefined
@@ -239,7 +273,7 @@ export class ResidentHost {
 					const context: ResidentStepContext = Object.freeze({
 						agendaRevision: state.revision,
 						...(this.options.learning && state.learning
-							? { learning: freezeResidentLearning(state.learning) }
+							? { learning: freezeLearning(state.learning) }
 							: {}),
 					})
 					const execution =

package/src/manager/resident/initiative.ts

@@ -11,7 +11,11 @@ export const residentObservationSchema = z.object({
 	costUnits: cost.nullable(),
 })
 
-/** @experimental Host-validated outcome and measured resource use, never model self-confidence. */
+/**
+ * @experimental Host-validated outcome and measured resource use, never model self-confidence.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentObservation = Readonly<z.infer<typeof residentObservationSchema>>
 
 export const residentFeedbackSchema = z.object({
@@ -29,7 +33,11 @@ export const residentFeedbackSchema = z.object({
 		.max(8),
 })
 
-/** @experimental Last eight observations; best progress and stagnation survive eviction. */
+/**
+ * @experimental Last eight observations; best progress and stagnation survive eviction.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentFeedback = Readonly<
 	Omit<z.infer<typeof residentFeedbackSchema>, 'observations'>
 > & {
@@ -69,7 +77,11 @@ export function freezeResidentFeedback(value: ResidentFeedback): ResidentFeedbac
 	})
 }
 
-/** @experimental Policy units are chosen by the host; scores are heuristics, not probabilities. */
+/**
+ * @experimental Policy units are chosen by the host; scores are heuristics, not probabilities.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentSelectionConfig {
 	readonly progressValue: number
 	readonly initialExpectedProgress: number
@@ -77,7 +89,11 @@ export interface ResidentSelectionConfig {
 	readonly maxStagnantSteps?: number
 }
 
-/** @experimental Explainable inputs for a single selection; unknown cost is not zero. */
+/**
+ * @experimental Explainable inputs for a single selection; unknown cost is not zero.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentCandidate {
 	readonly pursuitId: string
 	readonly reason:
@@ -92,7 +108,11 @@ export interface ResidentCandidate {
 	readonly score: number | null
 }
 
-/** @experimental Choice is bound to the whole agenda revision used to compute it. */
+/**
+ * @experimental Choice is bound to the whole agenda revision used to compute it.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentSelection {
 	readonly agendaRevision: number
 	readonly pursuitId: string | null
@@ -100,7 +120,11 @@ export interface ResidentSelection {
 	readonly candidates: readonly ResidentCandidate[]
 }
 
-/** @experimental Pure local selection; perform inference inside budgeted steps, not here. */
+/**
+ * @experimental Pure local selection; perform inference inside budgeted steps, not here.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentSelector = (agenda: ResidentAgendaState, now: number) => ResidentSelection
 
 function meanObservedCost(observations: readonly ResidentObservation[]): number {
@@ -119,6 +143,8 @@ function meanObservedCost(observations: readonly ResidentObservation[]): number
  * @experimental Cost-aware continuation with an explicit abstention choice.
  * This is a measured-progress heuristic, not Bayesian value of computation.
  * A finite bootstrap allowance permits delayed payoffs but may stop too early.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function createResidentSelector(config: ResidentSelectionConfig): ResidentSelector {
 	const policy = z

package/src/manager/resident/loop.ts

@@ -6,10 +6,18 @@ import {
 	type ResidentState,
 } from './store.js'
 
-/** @experimental Developer-owned step; bind providers, tools and budgets in the host. */
+/**
+ * @experimental Developer-owned step; bind providers, tools and budgets in the host.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentStep = (state: ResidentState, signal: AbortSignal) => Promise<ResidentDecision>
 
-/** @experimental No model is invoked for an idle, terminal or unresolved resident. */
+/**
+ * @experimental No model is invoked for an idle, terminal or unresolved resident.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentStepResult =
 	| { status: 'settled'; state: ResidentState }
 	| {
@@ -18,7 +26,11 @@ export type ResidentStepResult =
 			state: ResidentState
 	  }
 
-/** @experimental A failed/aborted callback leaves its durable claim unresolved. */
+/**
+ * @experimental A failed/aborted callback leaves its durable claim unresolved.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export async function stepResident(
 	store: ResidentExecutionStore,
 	step: ResidentStep,
@@ -53,7 +65,11 @@ export async function stepResident(
 	}
 }
 
-/** @experimental Bounded local driver; not a daemon, process recovery service or notification transport. */
+/**
+ * @experimental Bounded local driver; not a daemon, process recovery service or notification transport.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentLoopOptions {
 	readonly store: ResidentExecutionStore
 	readonly step: ResidentStep
@@ -68,6 +84,8 @@ export interface ResidentLoopOptions {
  * @experimental Continue a pursuit without a new user message. Null wake times
  * and terminal states stop immediately; cancellation also interrupts idle waits.
  * An abort cannot undo callback effects or forcibly stop a callback ignoring its signal.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export async function runResident(options: ResidentLoopOptions): Promise<ResidentStepResult> {
 	const maxIdleMs = options.maxIdleMs ?? 60_000

package/src/manager/resident/outbox.ts

@@ -18,7 +18,11 @@ export const residentMessageInputSchema = z.object({
 	notBefore: time,
 })
 
-/** @experimental Host-approved content and an opaque destination route, never credentials. */
+/**
+ * @experimental Host-approved content and an opaque destination route, never credentials.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentMessageInput = Readonly<z.infer<typeof residentMessageInputSchema>>
 
 export const residentOutboxMessageSchema = residentMessageInputSchema
@@ -47,7 +51,11 @@ export const residentOutboxMessageSchema = residentMessageInputSchema
 			context.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid outbox lifecycle.' })
 	})
 
-/** @experimental Acknowledgment proves transport acceptance, not human reading. */
+/**
+ * @experimental Acknowledgment proves transport acceptance, not human reading.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentOutboxMessage = Readonly<z.infer<typeof residentOutboxMessageSchema>>
 
 export const residentDeliveryOutcomeSchema = z.discriminatedUnion('kind', [
@@ -59,10 +67,18 @@ export const residentDeliveryOutcomeSchema = z.discriminatedUnion('kind', [
 	}),
 ])
 
-/** @experimental Retry only with evidence of non-acceptance; null retryAt ends delivery. */
+/**
+ * @experimental Retry only with evidence of non-acceptance; null retryAt ends delivery.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentDeliveryOutcome = Readonly<z.infer<typeof residentDeliveryOutcomeSchema>>
 
-/** @experimental Atomic admission and exact-claim settlement, without automatic claim expiry. */
+/**
+ * @experimental Atomic admission and exact-claim settlement, without automatic claim expiry.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentOutboxStore {
 	read(): Promise<ResidentAgendaState | null>
 	claimMessage(
@@ -77,7 +93,11 @@ export interface ResidentOutboxStore {
 	): Promise<ResidentOutboxMessage>
 }
 
-/** @experimental A synchronous host policy, evaluated before claiming and again before sending. */
+/**
+ * @experimental A synchronous host policy, evaluated before claiming and again before sending.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentDeliveryGate = (
 	message: ResidentOutboxMessage,
 	now: number,
@@ -89,20 +109,32 @@ export type ResidentDeliveryGate = (
 			readonly reason: string
 	  }
 
-/** @experimental Bind an authorized route; forward message.id as the stable idempotency key. */
+/**
+ * @experimental Bind an authorized route; forward message.id as the stable idempotency key.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentMessageTransport = (
 	message: ResidentOutboxMessage,
 	signal: AbortSignal,
 ) => Promise<ResidentDeliveryOutcome>
 
-/** @experimental One dispatch admission, with no model invocation, polling or implicit retries. */
+/**
+ * @experimental One dispatch admission, with no model invocation, polling or implicit retries.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentDeliveryOptions {
 	readonly signal: AbortSignal
 	readonly gate: ResidentDeliveryGate
 	readonly now?: () => number
 }
 
-/** @experimental An idle result never asserts a message reached its destination. */
+/**
+ * @experimental An idle result never asserts a message reached its destination.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentDeliveryResult =
 	| { readonly status: 'settled'; readonly message: ResidentOutboxMessage }
 	| {
@@ -223,6 +255,8 @@ function admission(gate: ResidentDeliveryGate, message: ResidentOutboxMessage, n
  * @experimental Persist one send claim before calling a host-owned transport.
  * Throws, malformed outcomes and cancellation keep the claim unresolved. Stop
  * old executors and inspect effects before explicit settleMessage reconciliation.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export async function deliverResidentMessage(
 	store: ResidentOutboxStore,

package/src/manager/resident/proposal.ts

@@ -27,7 +27,11 @@ export const residentProposalLimitsSchema = z.object({
 	maxDepth: z.number().int().min(1).max(4),
 })
 
-/** @experimental An inert subgoal proposal; creating it grants no execution authority. */
+/**
+ * @experimental An inert subgoal proposal; creating it grants no execution authority.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentProposal {
 	readonly id: string
 	readonly parentId: string
@@ -38,7 +42,11 @@ export interface ResidentProposal {
 	readonly evidenceKey: string
 }
 
-/** @experimental Host-approved routing domains and finite subgoal admission bounds. */
+/**
+ * @experimental Host-approved routing domains and finite subgoal admission bounds.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentProposalLimits {
 	readonly domains: readonly string[]
 	readonly maxChildrenPerParent: number
@@ -56,13 +64,19 @@ export const residentProposalOriginSchema = z.object({
 	depth: z.number().int().min(1).max(4),
 })
 
-/** @experimental Host-admitted ancestry and evidence for a resident subgoal. */
+/**
+ * @experimental Host-admitted ancestry and evidence for a resident subgoal.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentProposalOrigin = Readonly<z.infer<typeof residentProposalOriginSchema>>
 
 /**
  * @experimental Pure validation against one agenda snapshot. The host must
  * atomically bind this snapshot to admission. Domains are routing metadata;
  * this does not prove an objective fits its domain or authorize any tools.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function validateResidentProposal(
 	agenda: ResidentAgendaState,