@namzu/sdk 54.0.0 → 55.1.0

package/src/manager/resident/store.ts

@@ -28,7 +28,11 @@ export const residentDecisionSchema = z.discriminatedUnion('kind', [
 	z.object({ kind: z.literal('blocked'), summary: text }),
 ])
 
-/** @experimental One bounded step's durable disposition; silence is not completion. */
+/**
+ * @experimental One bounded step's durable disposition; silence is not completion.
+ *
+ * @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 ResidentDecision = z.infer<typeof residentDecisionSchema>
 
 export const residentStateSchema = z
@@ -69,7 +73,11 @@ export const residentStateSchema = z
 		}
 	})
 
-/** @experimental Persisted identity and one pursuit, independent of a conversation. */
+/**
+ * @experimental Persisted identity and one pursuit, independent of a conversation.
+ *
+ * @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 ResidentState = Readonly<z.infer<typeof residentStateSchema>>
 
 /** Bounded addressing for local resident state. Stored scope is still validated. */
@@ -80,10 +88,18 @@ export function residentKeySegment(key: string): string {
 		: `~sha256-${createHash('sha256').update(encoded).digest('hex')}`
 }
 
-/** @experimental Minimal atomic contract needed to execute an existing pursuit. */
+/**
+ * @experimental Minimal atomic contract needed to execute an existing 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 ResidentExecutionStore = Pick<ResidentStore, 'read' | 'claim' | 'settle'>
 
-/** @experimental Backends must atomically compare revisions and publish admission before work. */
+/**
+ * @experimental Backends must atomically compare revisions and publish admission before work.
+ *
+ * @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 ResidentStore {
 	read(): Promise<ResidentState | null>
 	create(identity: string, objective: string): Promise<ResidentState>
@@ -92,7 +108,11 @@ export interface ResidentStore {
 	wake(expected: ResidentState, reason: string, now: number): Promise<ResidentState>
 }
 
-/** A competing owner advanced this resident's immutable revision. */
+/**
+ * A competing owner advanced this resident's immutable 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 class ResidentConflictError extends Error {
 	constructor() {
 		super('Resident state changed; read the current state before retrying.')
@@ -104,6 +124,8 @@ export class ResidentConflictError extends Error {
  * @experimental Local-filesystem state for one tenant/agent key and one pursuit.
  * A running claim never expires automatically: a crashed step may have effects.
  * Uses exclusive immutable revision publication, not a read/rename lock.
+ *
+ * @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 DiskResidentStore implements ResidentStore {
 	private readonly records = new DiskRevisionRecordStore<ResidentState>(

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

@@ -17,16 +17,28 @@ import type {
 	ResidentHistorySource,
 } from './history.js'
 
-/** @experimental Host authority for one pursuit, project and admission boundary. */
+/**
+ * @experimental Host authority for one pursuit, project and admission boundary.
+ *
+ * @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 ResidentToolEvidenceScope extends ResidentHistoryScope {
 	readonly projectId: string
 }
-/** @experimental Identity of an agenda-verified settlement, not a fabricated transcript. */
+/**
+ * @experimental Identity of an agenda-verified settlement, not a fabricated transcript.
+ *
+ * @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 ResidentSettledInvocation = Pick<
 	ResidentHistoryMatch,
 	'revision' | 'claimId' | 'step' | 'kind'
 >
-/** @experimental Settlement is checked before the host resolves the attempt's invocation. */
+/**
+ * @experimental Settlement is checked before the host resolves the attempt's invocation.
+ *
+ * @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 ResidentToolEvidenceOptions {
 	readonly history: ResidentHistorySource
 	readonly projectId: string
@@ -45,7 +57,11 @@ export interface ResidentToolEvidenceOptions {
 		signal?: AbortSignal,
 	) => Promise<SessionEvidenceSource>
 }
-/** @experimental An optional shared ceiling covers history, resolution and turn evidence. */
+/**
+ * @experimental An optional shared ceiling covers history, resolution and turn evidence.
+ *
+ * @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 ResidentToolEvidenceSearchOptions {
 	readonly query?: string
 	/** Token discovery: 1–16 terms, matched case-insensitively. Combined query/filter JSON ≤512 UTF-8 bytes. */
@@ -60,7 +76,11 @@ export interface ResidentToolEvidenceSearchOptions {
 	readonly refineTerms?: readonly string[]
 	readonly maxReadBytes?: number
 }
-/** @experimental Tool records from at most one settled invocation per bounded search page. */
+/**
+ * @experimental Tool records from at most one settled invocation per bounded search page.
+ *
+ * @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 ResidentToolEvidenceSearchResult {
 	readonly scope: ResidentToolEvidenceScope
 	readonly revision: number | null
@@ -75,20 +95,32 @@ export interface ResidentToolEvidenceSearchResult {
 	 */
 	readonly chargedBytes?: number
 }
-/** @experimental The revision is authorized anew on every read, including after restart. */
+/**
+ * @experimental The revision is authorized anew on every read, including after restart.
+ *
+ * @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 ResidentToolEvidenceReadOptions
 	extends Omit<SessionEvidenceReadOptions, 'maxReadBytes'> {
 	readonly revision: number
 	/** Shared operation ceiling, at most 8 MiB; reserves at least 1 MiB for turn evidence reads. */
 	readonly maxReadBytes?: number
 }
-/** @experimental Exact invocation text plus the settled claim that authorized access. */
+/**
+ * @experimental Exact invocation text plus the settled claim that authorized access.
+ *
+ * @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 ResidentToolEvidenceReadResult extends SessionEvidenceReadResult {
 	readonly revision: number
 	readonly claimId: string
 	readonly chargedBytes?: number
 }
-/** @experimental A host must bind tool access to the executing turn, not just this source. */
+/**
+ * @experimental A host must bind tool access to the executing turn, not just this source.
+ *
+ * @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 ResidentToolEvidenceSource {
 	readonly scope: ResidentToolEvidenceScope
 	readonly supportsTermRefinement?: boolean
@@ -102,7 +134,11 @@ export interface ResidentToolEvidenceSource {
 	): Promise<ResidentToolEvidenceReadResult>
 }
 
-/** @experimental Reuses the immutable agenda boundary; it never enumerates arbitrary sessions. */
+/**
+ * @experimental Reuses the immutable agenda boundary; it never enumerates arbitrary sessions.
+ *
+ * @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 createResidentToolEvidenceSource(
 	options: ResidentToolEvidenceOptions,
 ): ResidentToolEvidenceSource {

package/src/prompt/coding-agent-doctrine.ts

@@ -37,51 +37,49 @@ import type { PromptContribution } from './contributions.js'
 export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 
 ### Delivering work
-- Act when you have enough information. Do not re-derive facts already established, and do not re-open a decision the user has already made.
-- The requested scope is the deliverable. Do not quietly narrow it, widen it, or turn it into something adjacent. Read ambiguity the way a careful colleague would; make the routine judgment calls yourself and check in only when different readings would produce materially different work.
-- Finish the whole task, not just the easy parts. If one part is blocked — a tool or capability you do not have, an input that is missing — say so plainly, do not improvise a result for it, finish every other part in full, and say explicitly what you left out and why. Scaling the work down is the user's call.
+- Act when you have enough information. Take established facts and the user's decisions as settled.
+- The requested scope is the deliverable: deliver it at the size and on the subject it was asked. Read ambiguity the way a careful colleague would; make the routine judgment calls yourself and check in only when different readings would produce materially different work.
+- Finish the whole task, not just the easy parts. If one part is blocked — a tool or capability you do not have, an input that is missing — say so plainly instead of improvising a result for it, finish every other part in full, and say explicitly what you left out and why. Scaling the work down is the user's call.
 - If you find a real problem with the task as stated, say so in a sentence or two, then keep going under a stated assumption. Reserve blocking questions for cases where proceeding under any assumption would be unsafe or would make the work useless if wrong.
 - If the user repeats or reaffirms a request after you raised a concern, that is their decision: say so and do the full request.
 
 ### Reporting
 - Report outcomes faithfully. If tests fail, say so and show the output. If you skipped a step, say it was skipped. When something is done and verified, state it plainly without hedging.
-- Preserve exact identifiers when reporting evidence. Do not translate, normalize or correct their spelling.
-- Never present a green run on a subset as a green run. Name what was actually executed.
+- Report identifiers exactly as the evidence spells them, so the user can search for them.
+- Name what was actually executed, so a green run on a subset reads as that subset.
 - Reference code as \`path:line\` so the user can jump to it.
-- Correct an earlier statement only when the error would change the user's code, conclusions or decisions; state it once, plainly, and continue. No apologies, no tally of past mistakes.
+- Correct an earlier statement only when the error would change the user's code, conclusions or decisions; state it once, plainly, and continue, and keep apologies and tallies of past mistakes out of it, because they spend the reader's attention on the past.
 
 ### Using available evidence
-- Carry the active task and established facts across turns. A question or status request during ongoing work does not cancel that work unless the user says so. Ask for clarification when the intended change is genuinely unspecified; do not ask the user to repeat information already available.
-- Treat a successful tool result together with its exact inputs as evidence of what happened. Content you successfully wrote is available evidence, just like content you read. An announced action, proposed call, failed call, or another agent's unsupported claim is not proof of completion.
-- Match the source to the time the question asks about. For an earlier observation, use that observation or its retained original; a fresh read of a mutable source cannot establish what it contained earlier. For current state or a new action, check freshness as needed. If the historical detail is unavailable, say so instead of substituting today's value.
-- Reuse relevant evidence still available in conversation instead of observing it again by habit. Distinguish the last observed state from a guarantee that external state has not changed. Re-observe when evidence is missing, partial or invalidated, when another actor may have changed the target, or when freshness matters to the next action. If a check or exact-match edit reports a mismatch, inspect the current state and revise the action; do not force the old plan through.
-- When an observation is needed, ask the narrowest question that resolves the uncertainty. For a known file, inspect that file rather than listing the whole working directory. Recover missing observations with read-only tools, not by repeating a state-changing action.
+- Use what you have. Carry the active task and established facts across turns: a question or status request during ongoing work leaves that work in place unless the user says otherwise, and information already in the conversation needs no repeating. A successful tool result together with its exact inputs is evidence of what happened, and so is content you wrote; an announced action, a proposed call, a failed call or another agent's unsupported claim is not. Reuse evidence still in the conversation instead of observing it again by habit, and when you do observe, ask the narrowest question that resolves the uncertainty (a known file, not the whole working directory). Ask for clarification only when the intended change is genuinely unspecified.
+- Re-check what may have changed. Distinguish the last observed state from a guarantee that external state is unchanged, and observe again when evidence is missing, partial or invalidated, when another actor may have changed the target, or when freshness matters to the next action. If a check or exact-match edit reports a mismatch, inspect the current state and revise the action. Recover missing observations with read-only tools, because repeating a state-changing action changes state twice.
+- Say plainly when history is unavailable. Match the source to the time the question asks about: for an earlier observation use that observation or its retained original, since a fresh read of a mutable source cannot show what it held earlier. When the historical detail is gone, say so and leave today's value out of the answer.
 
 ### Reading and editing code
 - Before editing, use the relevant file content already available from a successful read or write; if it is unavailable or may be stale, read the needed portion. Read additional surrounding code when needed to match its naming and idiom. Respect project instructions and tool-specific prerequisites even when they require a fresh read.
-- Prefer the dedicated tools over shell equivalents: \`read\` over \`cat\`, the \`grep\` tool over running \`grep\` or \`rg\` through \`bash\`, \`glob\` over \`find\` or \`ls -R\`, \`edit\` over \`sed -i\`. To change an existing file use \`edit\`; use \`write\` only to create a file or when the user asked for a whole-file rewrite. Prefer their structured inputs and focused results; use shell commands when the task needs them, within the same configured permissions.
-- Independent tool calls go in one response. Reading three files, or running a grep and a glob, does not need three turns. Only group independent operations. Wait for a mutation to finish before an observation or another action that depends on it; runtime ordering and concurrency limits remain authoritative.
-- Match verification to the task and its risk. For a simple text-file operation, use the successful tool result and known content; do not run unrelated project tests or repeat a read merely to restate that result. For code changes, run the relevant tests, typecheck or lint that would catch a mistake, and follow required project checks. Never claim checks you did not run.
-- Never leave the working tree in a state you have not described. If you created scratch files, say where; if you touched files outside the request, say which.
+- Prefer the dedicated tools over shell equivalents (\`read\` over \`cat\`, \`grep\` over a shell grep, \`glob\` over \`find\`, \`edit\` over \`sed -i\`, \`write\` over a shell redirect), because their structured inputs and focused results are easier to check. Use \`bash\` when the task needs a shell; permissions apply the same way.
+- Independent tool calls go in one response: reading three files, or running a grep and a glob, does not need three turns. Wait for a mutation to finish before an observation or another action that depends on it; runtime ordering and concurrency limits remain authoritative.
+- Match verification to the task and its risk. For a simple text-file operation, the successful tool result and known content are enough, so an unrelated project test or a repeated read adds nothing. For code changes, run the relevant tests, typecheck or lint that would catch a mistake, and follow required project checks. Claim only the checks you ran.
+- Describe the state you leave the working tree in: say where scratch files are, and which files outside the request you touched.
 
 ### Working with git
 - Never push, force-push, reset, rebase, clean, or otherwise discard or rewrite history unless the user explicitly asked for that action. Approval for one push does not extend to the next.
 - Before any command that could discard uncommitted work, run \`git status\`. If there are changes there that you did not make, stop and ask rather than stashing, committing or discarding somebody else's work.
-- Commit only when the user asks, on the branch that is checked out. Do not create or switch branches unless the user asks or the project's instructions require it.
+- Commit only when the user asks, on the branch that is checked out. Create or switch branches only when the user asks or the project's instructions require it, because the checked-out branch is the user's working state.
 - After a broad \`git add\`, review what was staged before committing; a file whose name looks harmless can still carry a secret.
 - Never change git configuration or other persistent settings without asking: not \`user.name\` or \`user.email\`, hooks, remotes, credential helpers, or any \`git config\` (local or global), nor a shell profile or a tool's own config file. If a commit fails because no identity is set, stop and tell the user the command to set one; do not invent one.
 
 ### Keeping the user informed
 - Before a batch of tool calls, say in one short line what you are about to do and why. When you have been working for a while without saying anything, say in a few words where you are, then continue. One line, not a paragraph; the tool rows on screen already show the details.
-- Keep the final reply short and specific: what changed, what was verified, what is left. Do not restate the transcript.`
+- Keep the final reply short and specific: what changed, what was verified, what is left.`
 
 /**
  * Parent-only: rules about `task_create` / `task_update` and `Agent`, which a
  * delegated sub-agent does not have. See the module comment for the split.
  */
 export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
-- For work that is genuinely multi-step — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Do not open one for a single inspect-edit-test cycle; the list is for the user to follow, and a list of one item tells them nothing.
-- When the \`Agent\` tool is available, delegate genuinely independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Give each sub-agent the objective, relevant context and completion criteria; do not assume it sees context the delegation interface did not supply.
+- For work that is multi-step — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Skip it for a single inspect-edit-test cycle: the list is for the user to follow, and a list of one item tells them nothing.
+- When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. It starts with none of your context and returns what you ask for.
 - Delegate lookups — where something is defined, which files reference it, how a module works — with \`subagent_type: "explore"\`: it has reading and searching tools only and never interrupts the user for permission. Reserve the default sub-agent for work that changes files or runs commands.`
 
 /**
@@ -91,7 +89,7 @@ export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
  */
 export const PLAN_MODE_DOCTRINE = `## Plan mode
 
-You are in plan mode. Read, search and think; do not change anything. \`read\`, \`grep\`, \`glob\` and the other read-only tools work as usual, and you may keep a task list. Any \`edit\`, \`write\` or shell command that changes state will be refused, so do not attempt one.
+You are in plan mode. Read, search and think, and leave everything as it is. \`read\`, \`grep\`, \`glob\` and the other read-only tools work as usual, and you may keep a task list. Any \`edit\`, \`write\` or shell command that changes state will be refused, so plan around them.
 
 When you have understood the task, reply with the plan: what you would change, in which files, in what order, and what you would verify. Be concrete — name files and functions — and short enough to read in one screen. Then stop and wait; the user will leave plan mode to have the plan carried out, and that switch is their approval.`
 

package/src/prompt/resident-learning.ts

@@ -1,17 +1,25 @@
 import { z } from 'zod'
-import { freezeResidentLearning, projectResidentLearning } from '../manager/resident/learning.js'
+import { freezeLearning, projectLearning } from '../learning/skill.js'
 import { defineTool } from '../tools/defineTool.js'
 import type { ToolContext, ToolDefinition } from '../types/tool/index.js'
 import type { PromptContribution } from './contributions.js'
 import { type ResidentStepPromptOptions, createResidentStepContributions } from './resident-step.js'
 
-/** @experimental One admission's context and read-only access to its evaluated guidance. */
+/**
+ * @experimental One admission's context and read-only access to its evaluated guidance.
+ *
+ * @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 ResidentStepContextBundle {
 	readonly contributions: readonly PromptContribution[]
 	readonly tools: readonly ToolDefinition[]
 }
 
-/** @experimental The host must reject reads from runs outside the admitted scope. */
+/**
+ * @experimental The host must reject reads from runs outside the admitted scope.
+ *
+ * @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 ResidentStepContextOptions extends ResidentStepPromptOptions {
 	readonly authorizeLearningRead: (context: ToolContext) => boolean
 }
@@ -20,11 +28,13 @@ export interface ResidentStepContextOptions extends ResidentStepPromptOptions {
  * @experimental List guidance descriptions first; disclose complete bodies only
  * when requested. Selection is local to this admission, never persisted as a
  * preference or inferred from keywords. Mount both returned tools and context.
+ *
+ * @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 createResidentStepContext(
 	options: ResidentStepContextOptions,
 ): ResidentStepContextBundle {
-	const learning = options.learning ? freezeResidentLearning(options.learning) : undefined
+	const learning = options.learning ? freezeLearning(options.learning) : undefined
 	const contributions = createResidentStepContributions({
 		...options,
 		learning: learning ? { ...learning, skills: [] } : undefined,
@@ -35,8 +45,7 @@ export function createResidentStepContext(
 	const authorize = options.authorizeLearningRead
 	const resolveSources = options.resolveLearningSources
 	const selected = new Set<string>()
-	const profileChars = projectResidentLearning(learning, { maxChars: 12_000, skillNames: [] }).text
-		.length
+	const profileChars = projectLearning(learning, { maxChars: 12_000, skillNames: [] }).text.length
 	const project = (names: readonly string[], maxChars = 12_000) => {
 		let sources: ReturnType<NonNullable<typeof resolveSources>> = []
 		try {
@@ -44,7 +53,7 @@ export function createResidentStepContext(
 		} catch {
 			// Unavailable observations cannot establish a dependency match.
 		}
-		return projectResidentLearning(
+		return projectLearning(
 			{ ...learning, identity: undefined, preferences: [] },
 			{ maxChars, skillNames: names, sources },
 		)

package/src/prompt/resident-step.ts

@@ -1,10 +1,10 @@
-import type { ResidentHistoryScope } from '../manager/resident/history.js'
 import {
-	type ResidentLearningSource,
-	type ResidentLearningState,
-	freezeResidentLearning,
-	projectResidentLearning,
-} from '../manager/resident/learning.js'
+	type LearningSource,
+	type LearningState,
+	freezeLearning,
+	projectLearning,
+} from '../learning/skill.js'
+import type { ResidentHistoryScope } from '../manager/resident/history.js'
 import type { ResidentState } from '../manager/resident/store.js'
 import type { PromptContribution } from './contributions.js'
 
@@ -34,13 +34,17 @@ Use permitted reads and analysis. Do not change files, persistent memory or exte
 const HISTORY_GUIDANCE = `## Resident recall
 When the saved summary lacks an earlier decision or accepted input, use search_resident_history, then read_resident_history for exact retained text. Search without a query to browse recent steps. Follow pagination even after empty pages; incomplete searches cannot prove absence. Only earlier settled steps of this pursuit are available, within the supplied revision boundary. Part 0 is a historical summary, not an independent tool receipt; wake inputs are recorded claims. Later evidence can supersede earlier claims: check relevant newer steps and mutable sources before acting. Do not repeat an effect to recover its output. These tools do not restore unrecorded tool transcripts.`
 
-/** @experimental Host-selected context for one admitted resident step. */
+/**
+ * @experimental Host-selected context for one admitted resident 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 ResidentStepPromptOptions {
 	readonly state: ResidentState
 	/** The host-approved learning snapshot bound to this admission. */
-	readonly learning?: ResidentLearningState
+	readonly learning?: LearningState
 	/** Host resolves current dependency revisions for each model request. No model-generated revisions. */
-	readonly resolveLearningSources?: () => readonly ResidentLearningSource[]
+	readonly resolveLearningSources?: () => readonly LearningSource[]
 	/** Bound historical source whose read-only tools the host has mounted. */
 	readonly history?: ResidentHistoryScope
 	/** The host mounted scoped search_resident_tools/read_resident_tool capabilities. */
@@ -64,6 +68,8 @@ export interface ResidentStepPromptOptions {
  *
  * Project instructions and authorization remain on their existing host/runtime
  * paths. These contributions neither load project files nor authorize work.
+ *
+ * @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 createResidentStepContributions(
 	options: ResidentStepPromptOptions,
@@ -76,11 +82,11 @@ export function createResidentStepContributions(
 			options.history.pursuitId !== state.pursuitId)
 	)
 		throw new Error('Resident history context belongs to a different pursuit.')
-	const admittedLearning = options.learning ? freezeResidentLearning(options.learning) : undefined
+	const admittedLearning = options.learning ? freezeLearning(options.learning) : undefined
 	const boundNames =
 		admittedLearning?.skills.filter((skill) => skill.sources?.length).map((skill) => skill.name) ??
 		[]
-	const learning = projectResidentLearning(admittedLearning, {
+	const learning = projectLearning(admittedLearning, {
 		maxChars: 12_000,
 		skillNames:
 			admittedLearning?.skills
@@ -137,13 +143,13 @@ export function createResidentStepContributions(
 						id: 'namzu.resident-step.source-bound-learning',
 						placement: 'context' as const,
 						render: () => {
-							let sources: readonly ResidentLearningSource[] = []
+							let sources: readonly LearningSource[] = []
 							try {
 								sources = resolveSources?.() ?? []
 							} catch {
 								/* Unavailable evidence withholds bound instructions. */
 							}
-							const projection = projectResidentLearning(
+							const projection = projectLearning(
 								admittedLearning
 									? { ...admittedLearning, identity: undefined, preferences: [] }
 									: undefined,

package/src/public-runtime.ts

@@ -333,6 +333,7 @@ export { drainQuery, query } from './runtime/query/index.js'
 export {
 	collapseProjectInstructionSnapshots,
 	isProjectInstructionMessage,
+	projectInstructionBody,
 	replaceProjectInstructionSnapshot,
 } from './runtime/query/project-instructions.js'
 // Mid-run guidance. A host holds the channel and the loop drains it at the
@@ -1472,6 +1473,8 @@ export {
 } from './runtime/query/auto-review/index.js'
 // What the model is told when a person declines a call without words of their own.
 export { DECLINED_TOOL_CALL_FEEDBACK } from './runtime/query/declined.js'
+// Whether a tool result answers a call the review did not let run, so a host counting failures can leave it out.
+export { isReviewRefusalResult } from './runtime/query/iteration/phases/per-call-review.js'
 
 // The system prompt is open: a contribution registry the assembler
 // consumes, with skills as its first contributor. See `prompt/contributions.ts`.
@@ -1650,11 +1653,31 @@ export { validateResidentProposal } from './manager/resident/proposal.js'
 export { deliverResidentMessage } from './manager/resident/outbox.js'
 export { createResidentDeliveryWindow } from './manager/resident/delivery-window.js'
 
+export { hashLearningSkill, projectLearning } from './learning/skill.js'
+export { runLearningCycle } from './learning/cycle.js'
 export {
-	hashResidentSkill,
-	projectResidentLearning,
-} from './manager/resident/learning.js'
-export { runResidentLearningCycle } from './manager/resident/learning-cycle.js'
+	LEARNING_FLOOR_COMPONENTS,
+	LEARNING_SURFACE_KINDS,
+	learningExperienceFromCycle,
+	proposeLearningCandidate,
+	resolveLearningSurface,
+} from './learning/generator.js'
+export {
+	LEARNING_CONFIDENCE_LEVELS,
+	LEARNING_EDIT_VERDICTS,
+	normalizeLearningExperience,
+	selectLearningExperience,
+} from './learning/experience.js'
+export {
+	LEARNING_EXPERIENCE_STORE_VERSION,
+	SqliteLearningExperienceStore,
+} from './learning/experience-store.js'
+export {
+	LearningLeakError,
+	assertNoLearningLeak,
+	createLearningCanary,
+	scanForLearningLeak,
+} from './learning/leak-tripwire.js'
 
 export {
 	createSessionEvidenceSource,
@@ -1669,11 +1692,19 @@ export { createResidentToolEvidenceSource } from './manager/resident/tool-eviden
 
 export { createResidentEvidenceRecallStep } from './manager/resident/evidence-recall.js'
 
+export {
+	SqliteLearningStore,
+	runStoredLearningCycle,
+	runStoredLearningFromObservations,
+} from './learning/store.js'
 export {
 	SqliteResidentLearningStore,
+	hashResidentSkill,
+	projectResidentLearning,
+	runResidentLearningCycle,
 	runStoredResidentLearningCycle,
 	runStoredResidentLearningFromObservations,
-} from './manager/resident/learning-store.js'
+} from './learning/deprecated.js'
 
 // ─── sessions, turns and the session log ─────────────────────────────────
 //

package/src/public-types.ts

@@ -607,29 +607,58 @@ export type {
 	ResidentContextualStep,
 } from './manager/resident/host.js'
 export type {
-	ResidentLearningEvidence,
-	ResidentSkillCandidate,
-	ResidentLearnedSkill,
-	ResidentLearningState,
-	ResidentProfileUpdate,
-	ResidentSkillEvaluation,
-	ResidentLearningProjectionOptions,
-	ResidentLearningSource,
-	ResidentLearningProjection,
-} from './manager/resident/learning.js'
-export type {
-	ResidentLearningStage,
-	ResidentLearningReceipt,
-	ResidentLearningConsumption,
-	ResidentLearningCycleEvent,
-	ResidentLearningCycleContext,
-	ResidentLearningGenerationContext,
-	ResidentLearningExplorationContext,
-	ResidentLearningExploration,
-	ResidentLearningEvaluationContext,
-	ResidentLearningCycleOptions,
-	ResidentLearningCycleResult,
-} from './manager/resident/learning-cycle.js'
+	LearningEvidence,
+	LearningSkillCandidate,
+	LearnedSkill,
+	LearningState,
+	LearningProfileUpdate,
+	LearningSkillEvaluation,
+	LearningProjectionOptions,
+	LearningSource,
+	LearningProjection,
+} from './learning/skill.js'
+export type {
+	LearningStage,
+	LearningReceipt,
+	LearningConsumption,
+	LearningCycleEvent,
+	LearningCycleContext,
+	LearningGenerationContext,
+	LearningExplorationContext,
+	LearningExploration,
+	LearningEvaluationContext,
+	LearningCycleOptions,
+	LearningCycleResult,
+} from './learning/cycle.js'
+
+export type {
+	LearningModel,
+	LearningModelReply,
+	LearningModelRequest,
+	LearningProposal,
+	LearningProposeOptions,
+	LearningProposedEdit,
+	LearningSurface,
+	LearningSurfaceKind,
+} from './learning/generator.js'
+
+export type {
+	LearningConfidence,
+	LearningEditRow,
+	LearningEditVerdict,
+	LearningExperienceEntry,
+	LearningExperienceInput,
+	LearningExperienceQuery,
+	LearningLesson,
+} from './learning/experience.js'
+export type { SqliteLearningExperienceStoreOptions } from './learning/experience-store.js'
+
+export type {
+	LearningLeakGuard,
+	LearningLeakKind,
+	LearningLeakFinding,
+	LearningLeakSubject,
+} from './learning/leak-tripwire.js'
 
 export type {
 	ResidentArchiveRequest,
@@ -678,18 +707,18 @@ export type {
 } from './turn/json-claim-verifier.js'
 
 export type {
-	SqliteResidentLearningStoreOptions,
-	ResidentLearningArtifact,
-	ResidentLearningRecordedUsage,
-	ResidentLearningCycleSummary,
-	ResidentLearningDiscoveryOptions,
-	ResidentLearningDiscoveryResult,
-} from './manager/resident/learning-store.js'
+	SqliteLearningStoreOptions,
+	LearningArtifact,
+	LearningRecordedUsage,
+	LearningCycleSummary,
+	LearningDiscoveryOptions,
+	LearningDiscoveryResult,
+} from './learning/store.js'
 export type {
-	ResidentLearningObservation,
-	ResidentLearningObservationRecord,
-	ResidentLearningTarget,
-} from './manager/resident/learning-observation.js'
+	LearningObservation,
+	LearningObservationRecord,
+	LearningTarget,
+} from './learning/observation.js'
 
 // ─── sessions, turns and the session log: paths and log lines ────────────
 // The session types themselves come through `./types/session/index.js` above.
@@ -818,3 +847,36 @@ export type {
 } from './pals/activity/subscription-policy.js'
 export type { PalActivitySubscriptionRunnerOptions } from './pals/activity/subscriptions.js'
 export type { PalActivityCausalityOptions } from './pals/activity/causality.js'
+
+// Deprecated resident-prefixed names, kept until the next major.
+export type {
+	ResidentLearningEvidence,
+	ResidentSkillCandidate,
+	ResidentLearnedSkill,
+	ResidentLearningState,
+	ResidentProfileUpdate,
+	ResidentSkillEvaluation,
+	ResidentLearningProjectionOptions,
+	ResidentLearningSource,
+	ResidentLearningProjection,
+	ResidentLearningStage,
+	ResidentLearningReceipt,
+	ResidentLearningConsumption,
+	ResidentLearningCycleEvent,
+	ResidentLearningCycleContext,
+	ResidentLearningGenerationContext,
+	ResidentLearningExplorationContext,
+	ResidentLearningExploration,
+	ResidentLearningEvaluationContext,
+	ResidentLearningCycleOptions,
+	ResidentLearningCycleResult,
+	SqliteResidentLearningStoreOptions,
+	ResidentLearningArtifact,
+	ResidentLearningRecordedUsage,
+	ResidentLearningCycleSummary,
+	ResidentLearningDiscoveryOptions,
+	ResidentLearningDiscoveryResult,
+	ResidentLearningObservation,
+	ResidentLearningObservationRecord,
+	ResidentLearningTarget,
+} from './learning/deprecated.js'